Skip to content

GitLab CI/CD Runner on Mac Mini M4: Complete Guide

Install and configure a GitLab CI/CD runner on a dedicated Mac Mini M4. Build iOS apps natively on Apple Silicon, run tests on real simulators, and deploy to TestFlight, all from your GitLab pipeline.

CI/CD 30 min read Updated November 2026

Why Self-Hosted GitLab Runners on Mac?

GitLab offers shared runners on Linux, but building iOS apps requires macOS running on Apple hardware. GitLab's own macOS shared runners are limited and expensive. A self-hosted Mac Mini M4 runner gives you:

  • Unlimited CI/CD Minutes

    GitLab's free tier includes 400 CI/CD minutes on shared runners. On self-hosted, there is no limit.

  • Native Apple Silicon

    Build on the same M4 chip your users' devices run. No Rosetta translation overhead.

  • Full Environment Control

    Install any Xcode version, simulators, tools, and dependencies you need.

  • Persistent Caches

    DerivedData, SPM packages, and CocoaPods caches survive between pipeline runs.

Install GitLab Runner

SSH into your dedicated Mac mini M4 build server and install GitLab Runner, plus xcbeautify for readable build logs, with Homebrew:

# Connect to your Mac Mini M4
ssh admin@your-server-ip

# Put the preinstalled Homebrew on your PATH (once per account)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# Install GitLab Runner with Homebrew, plus xcbeautify for the pipeline's build logs
brew install gitlab-runner xcbeautify

# Verify installation (prints the version and OS/Arch: darwin/arm64)
gitlab-runner --version

Install as a macOS Service

# Run the runner as a launchd service. It is a LaunchAgent: it starts when
# your user session starts, so on a headless Mac enable automatic login for
# this user (System Settings > Users & Groups) to bring it back after a reboot
brew services start gitlab-runner

# Verify the service is running
brew services list | grep gitlab-runner
# gitlab-runner started admin ~/Library/LaunchAgents/homebrew.mxcl.gitlab-runner.plist

Register the Runner

Go to your GitLab project and open Settings > CI/CD > Runners, then select Create project runner (for a group: Build > Runners > Create group runner). In Tags, enter macos and m4 (the pipeline below targets them), create the runner, then copy its runner authentication token, which starts with glrt-. With an authentication token, the register command does not accept tags or the other runner options: you set them here in GitLab. To script this step, create the runner with the API instead (example below).

Register with a Runner Authentication Token

# Optional: create the runner with the API instead of the GitLab UI.
# Needs an access token with the create_runner scope; the "token"
# field of the response is the runner authentication token (glrt-...)
curl --request POST \
  --header "PRIVATE-TOKEN: YOUR_ACCESS_TOKEN" \
  --url "https://gitlab.com/api/v4/user/runners" \
  --data "runner_type=project_type" \
  --data "project_id=YOUR_PROJECT_ID" \
  --data "tag_list=macos,m4" \
  --data "run_untagged=false"

# Register the runner with its authentication token (starts with glrt-).
# Tags, untagged jobs and locking come from the runner you created in GitLab:
# do not pass --tag-list or --run-untagged with an authentication token
gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "YOUR_RUNNER_AUTHENTICATION_TOKEN" \
  --executor "shell" \
  --name "mac-mini-m4-runner"

# Confirm the runner can reach GitLab
gitlab-runner verify

Legacy: Register with a Registration Token

Registration tokens have been deprecated since GitLab 15.6, and GitLab plans to remove them in GitLab 20.0. Since GitLab 17.0, they only work if an administrator (or, on GitLab.com, the owner of the top-level group) has enabled them again. Use this method only on an instance that still requires it.

# Legacy: registration token (deprecated since GitLab 15.6,
# removal scheduled for GitLab 20.0). On GitLab 17.0 and later,
# it works only where registration tokens were enabled again.
gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.com/" \
  --registration-token "YOUR_REGISTRATION_TOKEN" \
  --executor "shell" \
  --description "mac-mini-m4-runner" \
  --tag-list "macos,apple-silicon,m4,ios,xcode" \
  --run-untagged="false"

Verify Runner Configuration

# View the runner config file
cat ~/.gitlab-runner/config.toml

# Expected output:
# concurrent = 2
# check_interval = 0
#
# [session_server]
#   session_timeout = 1800
#
# [[runners]]
#   name = "mac-mini-m4-runner"
#   url = "https://gitlab.com/"
#   token = "..."
#   executor = "shell"
#   [runners.cache]
#     MaxUploadedArchiveSize = 0

# Adjust concurrency based on your hardware:
# Mac Mini M4 (16GB): concurrent = 2
# Mac Mini M4 Pro (24GB): concurrent = 3
# Mac Mini M4 Pro (48GB): concurrent = 4

Edit ~/.gitlab-runner/config.toml to adjust the concurrency:

# Edit the config
nano ~/.gitlab-runner/config.toml

# Set concurrent to match your hardware capacity
concurrent = 2

# Restart the service to apply changes
brew services restart gitlab-runner

The runner should now appear as Online in your GitLab project under Settings > CI/CD > Runners.

Create .gitlab-ci.yml for iOS

Create a .gitlab-ci.yml file in your repository root. This complete pipeline builds, tests, and deploys your iOS app:

# .gitlab-ci.yml

stages:
  - build
  - test
  - deploy

variables:
  SCHEME: "MyApp"
  WORKSPACE: "MyApp.xcworkspace"
  # Any device listed by: xcrun simctl list devices available
  DESTINATION: "platform=iOS Simulator,name=iPhone 17,OS=latest"
  # Pick the Xcode for every job without sudo
  # (preinstalled Xcode; for another version, use the path from xcodes installed)
  DEVELOPER_DIR: "/Applications/Xcode.app/Contents/Developer"

# Only run on our Mac runner
default:
  tags:
    - macos
    - m4
  before_script:
    # The runner cleans the checkout (git clean -ffdx) before each job, so keep
    # DerivedData outside it: one warm folder per project and concurrent job slot
    - export DERIVED_DATA="${CI_BUILDS_DIR}/DerivedData/${CI_PROJECT_PATH_SLUG}-${CI_CONCURRENT_PROJECT_ID}"
    - xcodebuild -version
    # Pods/ is removed with the rest of the checkout's untracked files: reinstall it
    - |
      if [ -f "Podfile" ]; then
        pod install
      fi

# ---- BUILD ----

build:
  stage: build
  script:
    - |
      xcodebuild build \
        -workspace "${WORKSPACE}" \
        -scheme "${SCHEME}" \
        -destination "${DESTINATION}" \
        -derivedDataPath "${DERIVED_DATA}" \
        CODE_SIGNING_ALLOWED=NO \
        | xcbeautify

# ---- TEST ----

unit_tests:
  stage: test
  needs: ["build"]
  script:
    - |
      xcodebuild test \
        -workspace "${WORKSPACE}" \
        -scheme "${SCHEME}" \
        -destination "${DESTINATION}" \
        -derivedDataPath "${DERIVED_DATA}" \
        -resultBundlePath "TestResults.xcresult" \
        -parallel-testing-enabled YES \
        | xcbeautify --report junit --report-path build/reports
  artifacts:
    when: always
    paths:
      - TestResults.xcresult/
    reports:
      junit: build/reports/junit.xml
    expire_in: 7 days
  after_script:
    - xcrun simctl shutdown all 2>/dev/null || true

# ---- DEPLOY ----

deploy_testflight:
  stage: deploy
  needs: ["unit_tests"]
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  script:
    - |
      # Install or update Fastlane
      which fastlane || brew install fastlane

      # Run Fastlane beta lane
      fastlane beta
  environment:
    name: testflight
  variables:
    MATCH_PASSWORD: ${MATCH_PASSWORD}
    # Names read by fastlane's app_store_connect_api_key action (call it in your lane)
    APP_STORE_CONNECT_API_KEY_KEY_ID: ${APP_STORE_KEY_ID}
    APP_STORE_CONNECT_API_KEY_ISSUER_ID: ${APP_STORE_ISSUER_ID}
    APP_STORE_CONNECT_API_KEY_KEY: ${APP_STORE_KEY_CONTENT}

Add CI/CD Variables in GitLab

Navigate to Settings > CI/CD > Variables in your GitLab project and add these variables as "Masked" and "Protected":

  • MATCH_PASSWORD: Password for Fastlane Match encryption
  • APP_STORE_KEY_ID: App Store Connect API Key ID
  • APP_STORE_ISSUER_ID: App Store Connect Issuer ID
  • APP_STORE_KEY_CONTENT: The .p8 key file contents

Optimize Performance

GitLab Cache Configuration

On a persistent Mac, the fastest cache is the one GitLab does not have to move: the pipeline above keeps DerivedData outside the checkout, so it stays warm between jobs. With the shell executor, GitLab's own cache is zipped and unzipped on every job, so keep it for small folders such as Pods/:

# DerivedData already stays on disk outside the checkout (DERIVED_DATA above).
# Use GitLab's cache for small folders, keyed on the lockfile:
build:
  cache:
    key:
      files:
        - Podfile.lock
    paths:
      - Pods/
    policy: pull-push

# For test jobs that don't modify the cache, use pull-only:
unit_tests:
  cache:
    key:
      files:
        - Podfile.lock
    paths:
      - Pods/
    policy: pull

Use Artifacts for Inter-Stage Data

# Useful when the build and test jobs can run on different Macs.
# build-for-testing compiles the app and its test bundles once; artifacts must
# sit inside the project folder, so this job builds there
build:
  script:
    - |
      xcodebuild build-for-testing \
        -workspace "${WORKSPACE}" \
        -scheme "${SCHEME}" \
        -destination "${DESTINATION}" \
        -derivedDataPath build/DerivedData \
        | xcbeautify
  artifacts:
    paths:
      - build/DerivedData/Build/Products/
    expire_in: 2 hours

# The test stage receives the built products and runs them without rebuilding
unit_tests:
  needs: ["build"]  # downloads the build job's artifacts
  script:
    - |
      xcodebuild test-without-building \
        -xctestrun build/DerivedData/Build/Products/*.xctestrun \
        -destination "${DESTINATION}" \
        | xcbeautify

Parallel Test Execution

# On one Mac, let xcodebuild split the test classes across simulator clones.
# (GitLab's parallel: keyword only helps if each copy runs a different part of
# the suite, using CI_NODE_INDEX and CI_NODE_TOTAL; otherwise it repeats it.)
unit_tests:
  stage: test
  script:
    - |
      xcodebuild test \
        -workspace "${WORKSPACE}" \
        -scheme "${SCHEME}" \
        -destination "${DESTINATION}" \
        -derivedDataPath "${DERIVED_DATA}" \
        -parallel-testing-enabled YES \
        -maximum-parallel-testing-workers 4 \
        | xcbeautify

Scheduled Cache Cleanup

# On the Mac Mini, set up a weekly cleanup cron job
crontab -e

# Add these lines:
# Every Sunday at 3 AM, remove DerivedData folders not used for 7 days
# (the pipeline keeps them in ~/builds/DerivedData, one per project and slot)
0 3 * * 0 find ~/builds/DerivedData -mindepth 1 -maxdepth 1 -type d -mtime +7 -exec rm -rf {} + 2>/dev/null

# Checkouts in ~/builds are reused by the next job (git fetch): no need to delete them

# Clean Homebrew cache monthly
0 5 1 * * /opt/homebrew/bin/brew cleanup --prune=30 2>/dev/null

Troubleshooting

Runner shows "offline" in GitLab

The runner runs as a LaunchAgent, so it starts when your user session starts: after a reboot it stays offline until that user logs in. On a headless Mac, enable automatic login for this user (System Settings > Users & Groups; not available while FileVault is on). Then check the service status and logs:

# Check service status
brew services list | grep gitlab-runner

# View logs
cat /opt/homebrew/var/log/gitlab-runner.log

# Restart the service
brew services restart gitlab-runner

# Verify connectivity to GitLab
gitlab-runner verify

Permission denied errors during builds

The runner may need access to the Xcode developer directory:

# Ensure the runner user has Xcode access (run once, in your SSH session)
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept

# If using simulators, ensure the user can access them
xcrun simctl list devices

Cache not being restored

Ensure cache keys are consistent and paths exist:

# Check cache directory permissions
ls -la ~/builds/

# The shell executor stores caches locally by default
# Verify the cache directory in config.toml:
cat ~/.gitlab-runner/config.toml

# Ensure [runners.cache] section has the right settings
# For local caching (most efficient for persistent runners):
# [runners.cache]
#   Type = ""  # empty = local cache

Xcode build hangs or times out

This is often caused by keychain access prompts or simulator issues:

# Unlock the keychain before builds
security unlock-keychain -p "YOUR_PASSWORD" ~/Library/Keychains/login.keychain-db

# Kill stuck simulators
xcrun simctl shutdown all
killall -9 com.apple.CoreSimulator.CoreSimulatorService 2>/dev/null || true

# Set a build timeout in .gitlab-ci.yml
build:
  timeout: 30 minutes

FAQ

Can I use a Docker executor on macOS?
Docker on macOS runs Linux containers in a VM, which cannot access macOS APIs, Xcode, or iOS simulators. For iOS builds, you must use the shell executor. Docker is fine for server-side Swift or other Linux-based tasks running alongside your Mac runner.
How do I register the runner for a GitLab group?
Open your GitLab group, go to Build > Runners and select Create group runner (you need the Owner role on the group). Register the Mac with the authentication token of that group runner. The runner then becomes available to all projects in the group.
Should I use the shell executor or SSH executor?
Use the shell executor. It runs commands directly on the Mac, which gives full access to Xcode, simulators, and the keychain. The SSH executor is for remote machines, which is unnecessary when the runner is already on the Mac.
Can I run both GitLab and GitHub Actions runners on the same Mac?
Yes. Both runners are lightweight and can coexist on the same Mac Mini M4. Just make sure to account for the combined resource usage when setting concurrency levels for each runner.
How do I update the GitLab Runner?
# Update via Homebrew
brew upgrade gitlab-runner

# Restart the service
brew services restart gitlab-runner

# Verify the new version
gitlab-runner --version
Looking for a fully managed GitLab Runner? Try Cloud-Runner Skip the setup entirely. Cloud-Runner provides pre-configured, dedicated GitLab Runners on Mac hardware, no installation or maintenance required.

Ready to Power Your GitLab Pipelines?

Get a dedicated Mac Mini M4 for your GitLab CI/CD runner. Unlimited builds starting at $85/month.

My Remote Mac prices in USD, excluding tax.

Looking for more detail?

Browse the full documentation for step-by-step setup, configuration references, and troubleshooting.

Open the documentation →