Configurer GitLab Runner sur un Mac pour vos builds iOS

Ce qu’il vous faut d’abord

• Un Mac Apple silicon avec accès administrateur et Xcode installé.
• Le premier lancement de Xcode fait. Lancez sudo xcodebuild -runFirstLaunch une fois si vous n’êtes pas sûr.
• Le droit de gérer les runners dans votre projet ou groupe GitLab.
• Une session de bureau sur le Mac, par partage d’écran ou avec un écran. La page d’installation macOS de GitLab demande un terminal graphique local, pas une session SSH.
• Le compte macOS qui exécutera les jobs. Ouvrez la session de bureau avec cet utilisateur.

1. Téléchargez le binaire du runner

GitLab indique ne pas maintenir la formule Homebrew et recommande le binaire officiel. Sur Apple silicon, prenez le build arm64. Un Mac neuf n’a pas forcément /usr/local/bin, donc créez-le d’abord.

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. Créez le runner dans GitLab

Les tokens d’enregistrement de runner sont dépréciés. GitLab prévoit de les supprimer dans GitLab 20.0. Le parcours actuel crée d’abord le runner dans l’interface, puis vous donne un token d’authentification de runner. Ce token commence par glrt-.

• Dans votre projet, ouvrez Settings, puis CI/CD, puis dépliez Runners.
• Sélectionnez Create project runner et choisissez macOS.
• Dans Tags, saisissez macos, xcode. Laissez Run untagged jobs désactivé, pour que seuls les jobs qui demandent un Mac arrivent ici.
• Sélectionnez Create runner et copiez le token. Il ne s’affiche que brièvement.

Les tags sont désormais portés par le runner dans GitLab. La documentation de GitLab indique que des réglages comme --tag-list et --run-untagged ne peuvent être définis qu’à la création du runner, dans l’interface ou par l’API. Modifiez ensuite les tags depuis la page Edit du runner.

3. Enregistrez-le avec l’executor shell

La page d’installation macOS de GitLab oriente vers l’executor shell pour les builds iOS et macOS. Les jobs tournent directement sur le Mac, sous votre utilisateur, avec Xcode et les simulateurs. Enregistrez-le sans questions interactives, comme ceci :

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"

Sur un GitLab auto-géré, utilisez plutôt l’URL de votre instance. Les réglages sont écrits dans ~/.gitlab-runner/config.toml. GitLab précise que l’executor shell est en mode maintenance. Il reçoit encore les correctifs de sécurité, et c’est toujours lui que la page macOS recommande pour le travail avec Xcode.

4. Installez et démarrez le service

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

Cela écrit ~/Library/LaunchAgents/gitlab-runner.plist. Sur macOS, le runner est un LaunchAgent utilisateur, et GitLab indique que c’est le seul mode pris en charge. Il tourne sous votre utilisateur, pas en root. Il peut accéder à votre trousseau et à votre session, ce dont le simulateur iOS et la signature de code ont besoin. Les logs vont dans ~/Library/Logs/gitlab-runner.out.log et gitlab-runner.err.log.

5. Faites-le survivre à un redémarrage

Un LaunchAgent démarre quand son utilisateur ouvre sa session et s’arrête à la déconnexion. Le runner ne revient donc après un redémarrage que si cet utilisateur se connecte tout seul. C’est pourquoi la documentation de GitLab demande d’activer la connexion automatique. Faites-le dans Réglages Système, sous Utilisateurs et groupes. Empêchez ensuite le Mac de se mettre en veille, et testez avec un vrai redémarrage.

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

La connexion automatique sur un Mac headless peut échouer en silence de plusieurs façons, dont une nouvelle dans macOS 27. Nous les avons décrites dans la connexion automatique sur un Mac headless.

6. Un .gitlab-ci.yml pour une app iOS

Un job ne tourne sur un runner que si le runner a tous les tags que le job demande. Ce job demande macos, lance les tests, et garde le result bundle même quand les tests échouent.

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 ligne rm -rf compte sur une machine qui garde sa copie de travail. xcodebuild refuse d’écraser un result bundle existant. Nous l’avons vérifié sur Xcode 26.6.

Erreurs courantes et solutions

Elles viennent de la section de dépannage macOS de GitLab.

• "launchctl" failed: Could not find domain for. Vous avez lancé install ou start par SSH. Ouvrez le Terminal sur le bureau du Mac et lancez-les là.
• FATAL: Failed to start gitlab-runner: exit status 134. Le service n’est pas installé correctement. Lancez gitlab-runner uninstall, puis install, puis start, depuis le bureau.
• killed: 9 sur Apple silicon. Les dossiers de logs indiqués dans le plist doivent exister et être accessibles en écriture par votre utilisateur.
• Failed to authorize rights (0x1) with status: -60007. Lancez DevToolsSecurity -enable et sudo security authorizationdb remove system.privilege.taskport is-developer.
• git fetch reste bloqué. Un Git installé par Homebrew peut ajouter un credential helper lié au trousseau. Lancez git config --global --add credential.helper '' avec l’utilisateur du runner.
• Un job reste bloqué. Ses tags ne correspondent pas à ceux du runner. Ou bien le job n’a pas de tag et le runner ne prend pas les jobs sans tag.

Pourquoi un Mac dédié aide

L’executor shell réutilise la même machine pour chaque job. Le DerivedData de Xcode, les checkouts de paquets Swift et les caches CocoaPods restent sur le disque entre les pipelines. C’est là que se joue le temps. Dans notre benchmark avec l’app iOS Wikipedia sur Xcode 26.6, nous avons chronométré un job typique après un petit changement. Il a pris 27 secondes sur un M6 déjà chaud. Le même job a pris 269 secondes sur un runner macos-26 neuf hébergé par GitHub. Un build propre a pris 86 secondes contre 183.

Quand les runners Mac hébergés par GitLab suffisent

GitLab propose ses propres runners macOS. Sa documentation, lue en octobre 2026, les présente comme une bêta. Ils sont réservés aux clients Premium et Ultimate et aux programmes open source. Les tailles sont un M1 avec 4 vCPU et 8 Go, et un M2 Pro avec 6 vCPU et 16 Go. Si vous avez l’une de ces offres et lancez quelques pipelines par jour, les runners hébergés vous épargnent toutes les étapes ci-dessus.

Ne choisissez pas un Mac dédié avec executor shell pour un projet public qui exécute des merge requests non fiables. GitLab prévient que les jobs shell peuvent lire le code des autres projets sur la même machine. Évitez aussi MacRun s’il vous faut une IP fixe pour une liste d’autorisation, un SLA ou plus d’une région. Nous ne proposons rien de tout cela.

Prêt à essayer sur notre matériel ? Notre page des autres systèmes de CI couvre le côté MacRun, et les tarifs listent tous les modèles.