Come configurare GitLab Runner su un Mac per le build iOS

Cosa ti serve prima

• Un Mac Apple silicon con accesso amministratore e Xcode installato.
• Il primo avvio di Xcode già fatto. Se non sei sicuro, esegui una volta sudo xcodebuild -runFirstLaunch.
• Il permesso di gestire i runner nel tuo progetto o gruppo GitLab.
• Una sessione desktop sul Mac, con la condivisione schermo o un monitor. La pagina di installazione macOS di GitLab dice di usare un terminale grafico locale, non una sessione SSH.
• L’account macOS che eseguirà i job. Accedi al desktop con quell’utente.

1. Scarica il binario del runner

GitLab dice di non mantenere la formula Homebrew e consiglia il binario ufficiale. Su Apple silicon usa la build arm64. Un Mac nuovo potrebbe non avere ancora /usr/local/bin, quindi crealo prima.

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. Crea il runner in GitLab

I token di registrazione dei runner sono deprecati. GitLab prevede di rimuoverli in GitLab 20.0. Con la procedura attuale crei prima il runner nell’interfaccia, poi ricevi un token di autenticazione del runner. Quel token inizia con glrt-.

• Nel progetto apri Settings, poi CI/CD, poi espandi Runners.
• Seleziona Create project runner e scegli macOS.
• In Tags inserisci macos, xcode. Lascia disattivato Run untagged jobs, così qui arrivano solo i job che chiedono un Mac.
• Seleziona Create runner e copia il token. Viene mostrato solo per poco.

Ora i tag stanno sul runner, in GitLab. La documentazione di GitLab dice che impostazioni come --tag-list e --run-untagged si possono impostare solo quando crei il runner, nell’interfaccia o con l’API. Per cambiare i tag in seguito usa la pagina Edit del runner.

3. Registralo con lo shell executor

La pagina di installazione macOS di GitLab indica lo shell executor per le build iOS e macOS. I job girano direttamente sul Mac, con il tuo utente, con Xcode e i simulatori. Registralo senza domande interattive così:

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"

Su GitLab self-managed usa invece l’URL della tua istanza. Le impostazioni finiscono in ~/.gitlab-runner/config.toml. GitLab segnala che lo shell executor è in modalità manutenzione. Riceve ancora le correzioni di sicurezza, ed è ancora quello che la pagina macOS consiglia per il lavoro con Xcode.

4. Installa e avvia il servizio

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

Questo scrive ~/Library/LaunchAgents/gitlab-runner.plist. Su macOS il runner è un LaunchAgent dell’utente, e GitLab dice che è l’unica modalità supportata. Gira con il tuo utente, non come root. Può accedere al tuo portachiavi e alla tua sessione, che servono al simulatore iOS e alla firma del codice. I log vanno in ~/Library/Logs/gitlab-runner.out.log e gitlab-runner.err.log.

5. Fallo sopravvivere a un riavvio

Un LaunchAgent parte quando il suo utente fa il login e si ferma al logout. Quindi il runner torna dopo un riavvio solo se quell’utente fa il login da solo. Per questo la documentazione di GitLab dice di attivare il login automatico. Fallo in Impostazioni di Sistema, in Utenti e gruppi. Poi impedisci al Mac di andare in stop e prova con un riavvio vero.

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

Il login automatico su un Mac headless può fallire in silenzio in diversi modi, uno dei quali è nuovo in macOS 27. Li abbiamo descritti in login automatico su un Mac headless.

6. Un .gitlab-ci.yml per un’app iOS

Un job gira su un runner solo se il runner ha tutti i tag elencati dal job. Questo job chiede macos, esegue i test e conserva il result bundle anche quando i test falliscono.

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

La riga rm -rf conta su una macchina che conserva la sua copia di lavoro. xcodebuild si rifiuta di sovrascrivere un result bundle esistente. Lo abbiamo verificato su Xcode 26.6.

Errori comuni e soluzioni

Vengono dalla sezione di troubleshooting macOS di GitLab.

• "launchctl" failed: Could not find domain for. Hai eseguito install o start via SSH. Apri il Terminale sul desktop del Mac ed eseguili lì.
• FATAL: Failed to start gitlab-runner: exit status 134. Il servizio non è installato correttamente. Dal desktop esegui gitlab-runner uninstall, poi install, poi start.
• killed: 9 su Apple silicon. Le cartelle dei log indicate nel plist devono esistere ed essere scrivibili dal tuo utente.
• Failed to authorize rights (0x1) with status: -60007. Esegui DevToolsSecurity -enable e sudo security authorizationdb remove system.privilege.taskport is-developer.
• git fetch si blocca. Un Git installato con Homebrew può aggiungere un credential helper del portachiavi. Esegui git config --global --add credential.helper '' con l’utente del runner.
• Un job resta bloccato. I suoi tag non corrispondono a quelli del runner, oppure il job non ha tag e il runner non accetta job senza tag.

Perché un Mac dedicato aiuta

Lo shell executor riusa la stessa macchina per ogni job. La DerivedData di Xcode, i checkout dei pacchetti Swift e le cache di CocoaPods restano sul disco tra una pipeline e l’altra. È lì che si perde tempo. Nel nostro benchmark con l’app iOS di Wikipedia su Xcode 26.6, abbiamo cronometrato un job tipico dopo una piccola modifica. Ha richiesto 27 secondi su un M6 caldo. Lo stesso job ha richiesto 269 secondi su un runner macos-26 nuovo ospitato da GitHub. Una build pulita ha richiesto 86 secondi contro 183.

Quando bastano i runner Mac ospitati da GitLab

GitLab ha i suoi runner macOS. La sua documentazione, letta a ottobre 2026, li indica come beta. Sono per i clienti Premium e Ultimate e per i programmi open source. Le dimensioni sono un M1 con 4 vCPU e 8 GB, e un M2 Pro con 6 vCPU e 16 GB. Se hai uno di quei piani ed esegui poche pipeline al giorno, i runner ospitati ti risparmiano tutti i passi qui sopra.

Non scegliere un Mac dedicato con shell executor per un progetto pubblico che esegue merge request non fidate. GitLab avverte che i job shell possono leggere il codice di altri progetti sulla stessa macchina. Lascia perdere MacRun anche se ti serve un IP statico per un allowlist, uno SLA o più di una regione. Non offriamo nessuna di queste cose.

Vuoi provarlo sul nostro hardware? La nostra pagina sugli altri sistemi di CI copre la parte MacRun, e i prezzi elencano ogni taglio.