GitLab Runner auf einem Mac für iOS-Builds einrichten

Was Sie vorher brauchen

• Einen Mac mit Apple Silicon, Admin-Zugriff und installiertem Xcode.
• Den ersten Start von Xcode. Führen Sie im Zweifel einmal sudo xcodebuild -runFirstLaunch aus.
• Die Berechtigung, Runner in Ihrem GitLab-Projekt oder Ihrer Gruppe zu verwalten.
• Eine Desktop-Sitzung auf dem Mac, per Bildschirmfreigabe oder mit Monitor. Laut der macOS-Installationsseite von GitLab brauchen Sie ein lokales Terminal in der grafischen Oberfläche, keine SSH-Sitzung.
• Das macOS-Konto, das die Jobs ausführen soll. Melden Sie sich als dieser Benutzer am Desktop an.

1. Das Runner-Binary herunterladen

GitLab pflegt nach eigener Aussage die Homebrew-Formel nicht und empfiehlt das offizielle Binary. Nehmen Sie auf Apple Silicon den arm64-Build. Auf einem frischen Mac gibt es /usr/local/bin eventuell noch nicht. Legen Sie es also zuerst an.

sudo mkdir -p /usr/local/bin
sudo curl --output /usr/local/bin/gitlab-runner \
  "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-darwin-arm64"
sudo chmod +x /usr/local/bin/gitlab-runner
gitlab-runner --version

2. Den Runner in GitLab anlegen

Registrierungstokens für Runner sind veraltet. GitLab will sie mit GitLab 20.0 entfernen. Beim aktuellen Ablauf legen Sie den Runner zuerst in der Oberfläche an. Dann bekommen Sie ein Authentifizierungstoken für den Runner. Es beginnt mit glrt-.

• Öffnen Sie in Ihrem Projekt Settings, dann CI/CD, und klappen Sie Runners auf.
• Wählen Sie Create project runner und dann macOS.
• Tragen Sie unter Tags macos, xcode ein. Lassen Sie Run untagged jobs aus. Dann landen hier nur Jobs, die nach einem Mac fragen.
• Wählen Sie Create runner und kopieren Sie das Token. Es wird nur kurz angezeigt.

Tags liegen jetzt beim Runner in GitLab. Laut der Doku von GitLab lassen sich Einstellungen wie --tag-list und --run-untagged nur beim Anlegen des Runners setzen, in der Oberfläche oder per API. Tags ändern Sie später auf der Edit-Seite des Runners.

3. Mit dem Shell Executor registrieren

Die macOS-Installationsseite von GitLab verweist für iOS- und macOS-Builds auf den Shell Executor. Jobs laufen direkt auf dem Mac, als Ihr Benutzer, mit Xcode und den Simulatoren. So registrieren Sie ohne Rückfragen:

export RUNNER_TOKEN="glrt-paste-your-token-here"
gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "shell" \
  --description "mac-mini-m6"

Bei selbst verwaltetem GitLab nehmen Sie stattdessen die URL Ihrer Instanz. Die Einstellungen landen in ~/.gitlab-runner/config.toml. GitLab weist darauf hin, dass der Shell Executor im Wartungsmodus ist. Er bekommt weiter Sicherheitsupdates, und die macOS-Seite empfiehlt ihn weiterhin für Xcode-Arbeit.

4. Den Dienst installieren und starten

cd ~
gitlab-runner install
gitlab-runner start
gitlab-runner status

Das schreibt ~/Library/LaunchAgents/gitlab-runner.plist. Unter macOS ist der Runner ein LaunchAgent des Benutzers, und laut GitLab ist das der einzige unterstützte Modus. Er läuft als Sie, nicht als root. So erreicht er Ihren Schlüsselbund und Ihre Anmeldesitzung, die der iOS-Simulator und die Code-Signierung brauchen. Die Logs landen in ~/Library/Logs/gitlab-runner.out.log und gitlab-runner.err.log.

5. Neustarts überstehen

Ein LaunchAgent startet, wenn sich sein Benutzer anmeldet, und stoppt bei der Abmeldung. Der Runner kommt nach einem Neustart also nur zurück, wenn sich dieser Benutzer von selbst anmeldet. Deshalb sagt die Doku von GitLab, Sie sollen die automatische Anmeldung einschalten. Das geht in den Systemeinstellungen unter Benutzer:innen & Gruppen. Verhindern Sie dann den Ruhezustand des Mac und testen Sie mit einem echten Neustart.

sudo pmset -a sleep 0
sudo shutdown -r now
# after it comes back, over SSH:
gitlab-runner status

Die automatische Anmeldung auf einem Headless-Mac kann auf einige Arten still scheitern, darunter eine neue in macOS 27. Wir haben sie in automatische Anmeldung auf einem Headless-Mac beschrieben.

6. Eine .gitlab-ci.yml für eine iOS-App

Ein Job läuft nur auf einem Runner, der alle Tags hat, die der Job nennt. Dieser Job fragt nach macos, führt die Tests aus und behält das Result Bundle auch dann, wenn Tests fehlschlagen.

stages:
  - test

ios_tests:
  stage: test
  tags:
    - macos
  script:
    - xcodebuild -version
    - rm -rf build/TestResults.xcresult
    - xcodebuild test -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17,OS=26.5' -resultBundlePath build/TestResults.xcresult
  artifacts:
    when: always
    paths:
      - build/TestResults.xcresult
    expire_in: 1 week

Die Zeile mit rm -rf ist wichtig auf einer Maschine, die ihre Arbeitskopie behält. xcodebuild weigert sich, ein vorhandenes Result Bundle zu überschreiben. Wir haben das mit Xcode 26.6 geprüft.

Häufige Fehler und Lösungen

Diese stammen aus dem macOS-Abschnitt zur Fehlerbehebung von GitLab.

• "launchctl" failed: Could not find domain for. Sie haben install oder start über SSH ausgeführt. Öffnen Sie das Terminal auf dem Desktop des Mac und führen Sie sie dort aus.
• FATAL: Failed to start gitlab-runner: exit status 134. Der Dienst ist nicht richtig installiert. Führen Sie gitlab-runner uninstall aus, dann install, dann start, vom Desktop aus.
• killed: 9 auf Apple Silicon. Die Log-Ordner aus der plist müssen existieren und für Ihren Benutzer beschreibbar sein.
• Failed to authorize rights (0x1) with status: -60007. Führen Sie DevToolsSecurity -enable und sudo security authorizationdb remove system.privilege.taskport is-developer aus.
• git fetch hängt. Ein Git aus Homebrew kann einen Credential-Helper für den Schlüsselbund hinzufügen. Führen Sie git config --global --add credential.helper '' als Runner-Benutzer aus.
• Ein Job hängt fest. Seine Tags passen nicht zu denen des Runners. Oder der Job hat keine Tags, und der Runner nimmt keine Jobs ohne Tags an.

Warum ein dedizierter Mac hilft

Der Shell Executor nutzt für jeden Job dieselbe Maschine. DerivedData von Xcode, Checkouts von Swift-Paketen und CocoaPods-Caches bleiben zwischen Pipelines auf der Platte. Genau dort geht die Zeit verloren. In unserem Benchmark mit der Wikipedia-iOS-App und Xcode 26.6 haben wir einen typischen Job nach einer kleinen Änderung gemessen. Er dauerte auf einem warmen M6 27 Sekunden. Derselbe Job dauerte auf einem frischen gehosteten macos-26-Runner von GitHub 269 Sekunden. Ein sauberer Build dauerte 86 Sekunden statt 183.

Wann die gehosteten Mac-Runner von GitLab reichen

GitLab betreibt eigene macOS-Runner. Laut der Doku, gelesen im Oktober 2026, sind sie im Beta-Status. Sie gibt es für Kunden mit Premium und Ultimate sowie für Open-Source-Programme. Die Größen sind ein M1 mit 4 vCPUs und 8 GB und ein M2 Pro mit 6 vCPUs und 16 GB. Haben Sie einen dieser Pläne und laufen nur ein paar Pipelines am Tag, sparen Ihnen gehostete Runner alle Schritte oben.

Nehmen Sie keinen dedizierten Mac mit Shell Executor für ein öffentliches Projekt, das nicht vertrauenswürdige Merge Requests ausführt. GitLab warnt, dass Shell-Jobs den Code anderer Projekte auf derselben Maschine lesen können. Lassen Sie MacRun auch weg, wenn Sie eine statische IP für eine Allowlist, ein SLA oder mehr als eine Region brauchen. Nichts davon bieten wir an.

Wollen Sie es auf unserer Hardware ausprobieren? Unsere Seite zu anderen CI-Systemen beschreibt die Seite von MacRun, und unter Preise finden Sie jede Stufe.