Zum Inhalt springen

GitLab CI/CD Runner auf Mac Mini M4: Vollständige Anleitung

Installieren und konfigurieren Sie einen GitLab CI/CD Runner auf einem dedizierten Mac Mini M4. Bauen Sie iOS-Apps nativ auf Apple Silicon, führen Sie Tests auf echten Simulatoren aus und deployen Sie zu TestFlight, alles aus Ihrer GitLab-Pipeline.

CI/CD 30 Min. Lesezeit Aktualisiert im November 2026

Warum Self-Hosted GitLab Runner auf Mac?

GitLab bietet Shared Runner unter Linux, aber das Bauen von iOS-Apps erfordert macOS auf Apple-Hardware. GitLabs eigene macOS-Shared-Runner sind eingeschränkt und teuer. Ein Self-Hosted Mac Mini M4 Runner bietet Ihnen:

  • Unbegrenzte CI/CD-Minuten

    GitLabs kostenlose Stufe umfasst 400 CI/CD-Minuten auf Shared Runnern. Auf Self-Hosted gibt es kein Limit.

  • Natives Apple Silicon

    Bauen Sie auf demselben M4-Chip, auf dem die Geräte Ihrer Nutzer laufen. Kein Rosetta-Übersetzungsaufwand.

  • Vollständige Umgebungskontrolle

    Installieren Sie jede Xcode-Version, Simulatoren, Tools und Abhängigkeiten, die Sie benötigen.

  • Persistente Caches

    DerivedData-, SPM-Pakete- und CocoaPods-Caches bleiben zwischen Pipeline-Durchläufen erhalten.

GitLab Runner installieren

Verbinden Sie sich per SSH mit Ihrem dedizierten Mac mini M4 Build Server und installieren Sie den GitLab Runner sowie xcbeautify für lesbare Build-Logs mit 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

Als macOS-Dienst installieren

# 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

Den Runner registrieren

Öffnen Sie Ihr GitLab-Projekt, gehen Sie zu Settings > CI/CD > Runners und wählen Sie Create project runner (für eine Gruppe: Build > Runners > Create group runner). Tragen Sie unter Tags macos und m4 ein (die Pipeline unten verwendet diese Tags), erstellen Sie den Runner und kopieren Sie anschließend sein Runner-Authentifizierungstoken, das mit glrt- beginnt. Mit einem Authentifizierungstoken akzeptiert der Befehl register weder Tags noch die übrigen Runner-Optionen: Sie legen sie hier in GitLab fest. Zum Automatisieren erstellen Sie den Runner stattdessen über die API (Beispiel unten).

Registrierung mit einem Runner-Authentifizierungstoken

# 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

Altes Verfahren: Registrierung mit einem Registrierungstoken

Registrierungstoken sind seit GitLab 15.6 veraltet, und GitLab plant, sie in GitLab 20.0 zu entfernen. Seit GitLab 17.0 funktionieren sie nur noch, wenn ein Administrator (oder auf GitLab.com der Eigentümer der Top-Level-Gruppe) sie wieder aktiviert hat. Verwenden Sie dieses Verfahren nur auf einer Instanz, die es noch erfordert.

# 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"

Runner-Konfiguration überprüfen

# 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

Bearbeiten Sie ~/.gitlab-runner/config.toml, um die Parallelität anzupassen:

# 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

Der Runner sollte nun als Online in Ihrem GitLab-Projekt unter Settings > CI/CD > Runners erscheinen.

.gitlab-ci.yml für iOS erstellen

Erstellen Sie eine .gitlab-ci.yml-Datei im Stammverzeichnis Ihres Repositorys. Diese vollständige Pipeline baut, testet und deployt Ihre 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}

CI/CD-Variablen in GitLab hinzufügen

Navigieren Sie zu Settings > CI/CD > Variables in Ihrem GitLab-Projekt und fügen Sie diese Variablen als "Masked" und "Protected" hinzu:

  • MATCH_PASSWORD: Passwort für die Fastlane Match-Verschlüsselung
  • APP_STORE_KEY_ID: App Store Connect API Key ID
  • APP_STORE_ISSUER_ID: App Store Connect Issuer ID
  • APP_STORE_KEY_CONTENT: Der Inhalt der .p8-Schlüsseldatei

Performance optimieren

GitLab Cache-Konfiguration

Auf einem persistenten Mac ist der schnellste Cache der, den GitLab nicht verschieben muss: Die Pipeline oben hält DerivedData außerhalb des Checkouts, sodass es zwischen den Jobs warm bleibt. Mit dem Shell-Executor wird GitLabs eigener Cache bei jedem Job gepackt und entpackt, nutzen Sie ihn daher für kleine Ordner wie 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

Artefakte für stufenübergreifende Daten verwenden

# 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

Parallele Testausführung

# 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

Geplante Cache-Bereinigung

# 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

Fehlerbehebung

Runner wird in GitLab als "offline" angezeigt

Der Runner läuft als LaunchAgent und startet daher mit Ihrer Benutzersitzung: Nach einem Neustart bleibt er offline, bis sich dieser Benutzer anmeldet. Aktivieren Sie auf einem headless Mac die automatische Anmeldung für diesen Benutzer (Systemeinstellungen > Benutzer & Gruppen; nicht verfügbar, solange FileVault aktiv ist). Überprüfen Sie dann den Status und die Logs des Runner-Dienstes:

# 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

Fehler "Permission denied" während der Builds

Der Runner benötigt möglicherweise Zugriff auf das Xcode-Entwicklerverzeichnis:

# 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 wird nicht wiederhergestellt

Stellen Sie sicher, dass die Cache-Schlüssel konsistent sind und die Pfade existieren:

# 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 hängt oder läuft in eine Zeitüberschreitung

Dies wird oft durch Schlüsselbund-Zugriffsaufforderungen oder Simulatorprobleme verursacht:

# 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

Kann ich einen Docker-Executor unter macOS verwenden?
Docker unter macOS führt Linux-Container in einer VM aus, die nicht auf macOS-APIs, Xcode oder iOS-Simulatoren zugreifen kann. Für iOS-Builds müssen Sie den Shell-Executor verwenden. Docker eignet sich für serverseitiges Swift oder andere Linux-basierte Aufgaben, die neben Ihrem Mac-Runner laufen.
Wie registriere ich den Runner für eine GitLab-Gruppe?
Öffnen Sie Ihre GitLab-Gruppe, gehen Sie zu Build > Runners und wählen Sie Create group runner (dafür benötigen Sie die Rolle Owner in der Gruppe). Registrieren Sie den Mac mit dem Authentifizierungstoken dieses Gruppen-Runners. Der Runner steht dann allen Projekten der Gruppe zur Verfügung.
Sollte ich den Shell-Executor oder den SSH-Executor verwenden?
Verwenden Sie den Shell-Executor. Er führt Befehle direkt auf dem Mac aus, was vollen Zugriff auf Xcode, Simulatoren und den Schlüsselbund gibt. Der SSH-Executor ist für Remote-Maschinen gedacht, was unnötig ist, wenn der Runner bereits auf dem Mac läuft.
Kann ich sowohl GitLab- als auch GitHub Actions-Runner auf demselben Mac ausführen?
Ja. Beide Runner sind leichtgewichtig und können auf demselben Mac Mini M4 koexistieren. Achten Sie nur darauf, den kombinierten Ressourcenverbrauch zu berücksichtigen, wenn Sie die Parallelitätsstufen für jeden Runner festlegen.
Wie aktualisiere ich den GitLab Runner?
# Update via Homebrew
brew upgrade gitlab-runner

# Restart the service
brew services restart gitlab-runner

# Verify the new version
gitlab-runner --version
Suchen Sie einen vollständig verwalteten GitLab Runner? Testen Sie Cloud-Runner Überspringen Sie die Einrichtung komplett. Cloud-Runner bietet vorkonfigurierte, dedizierte GitLab Runner auf Mac-Hardware, keine Installation oder Wartung erforderlich.

Bereit, Ihre GitLab-Pipelines zu betreiben?

Holen Sie sich einen dedizierten Mac Mini M4 für Ihren GitLab CI/CD Runner. Unbegrenzte Builds ab 85 $/Monat.

Preise von My Remote Mac in USD, exkl. Steuern.

Mehr Details gesucht?

Durchsuchen Sie die vollständige Dokumentation für Schritt-für-Schritt-Anleitungen, Konfigurationsreferenzen und Fehlerbehebung.

Dokumentation öffnen →