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üsselungAPP_STORE_KEY_ID: App Store Connect API Key IDAPP_STORE_ISSUER_ID: App Store Connect Issuer IDAPP_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?
Wie registriere ich den Runner für eine GitLab-Gruppe?
Sollte ich den Shell-Executor oder den SSH-Executor verwenden?
Kann ich sowohl GitLab- als auch GitHub Actions-Runner auf demselben Mac ausführen?
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