Faire tourner un agent Buildkite sur un Mac

Ce qu’il vous faut d’abord

• Un cluster Buildkite, et le droit de gérer ses tokens d’agent et ses queues. Vous devez être administrateur de l’organisation ou mainteneur du cluster.
• Un Mac sous macOS 11 ou plus récent. C’est le minimum annoncé par Buildkite. Apple silicon, Homebrew, Xcode et accès administrateur.
• Une clé SSH que l’agent peut utiliser pour cloner vos dépôts.

1. Créez une queue et un token d’agent

Dans Buildkite, sélectionnez Agents pour ouvrir la page Clusters, et choisissez votre cluster. Sur la page Queues, sélectionnez New Queue. Donnez-lui la clé macos et choisissez Self hosted. Ouvrez ensuite Agent Tokens, sélectionnez New Token, ajoutez une description, et créez-le. Copiez la valeur. Buildkite ne l’affiche qu’une fois.

Le formulaire du token a un champ Allowed IP Addresses. Laissez-le vide chez MacRun. Nos Mac n’ont pas d’IP publique fixe, donc une règle CIDR bloquerait l’agent.

2. Installez l’agent avec Homebrew

brew tap buildkite/buildkite
brew trust buildkite/buildkite
brew install buildkite/buildkite/buildkite-agent

Homebrew 7.0.7, la version présente sur notre Mac en octobre 2026, refuse les formules d’un tap tiers tant que vous ne lui faites pas confiance. C’est la ligne du milieu. La formule s’appelle désormais buildkite-agent@3, et l’ancien nom de la documentation de Buildkite pointe toujours vers elle.

Sur Apple silicon, les fichiers arrivent sous /opt/homebrew :

• Config : /opt/homebrew/etc/buildkite-agent/buildkite-agent.cfg
• Hooks : /opt/homebrew/etc/buildkite-agent/hooks
• Log : /opt/homebrew/var/log/buildkite-agent.log

Lancez brew info buildkite-agent pour voir les chemins exacts sur votre machine.

3. Ajoutez le token et le tag de queue

La documentation de Buildkite utilise sed pour remplacer le token d’exemple. Remplacez le texte en majuscules par votre token.

sed -i '' "s/xxx/INSERT-YOUR-AGENT-TOKEN-HERE/g" "$(brew --prefix)"/etc/buildkite-agent/buildkite-agent.cfg
cat "$(brew --prefix)"/etc/buildkite-agent/buildkite-agent.cfg | grep token

Ouvrez ensuite le même fichier et réglez la ligne tags, pour que l’agent rejoigne votre queue :

tags="queue=macos"

Un agent appartient à une seule queue self-hosted dans un cluster. Sans tag de queue, il rejoint la queue par défaut. Si le cluster n’a pas de queue self-hosted par défaut, Buildkite indique que l’agent ne parvient pas à se connecter.

4. Testez-le, puis lancez-le comme service

Démarrez-le une fois au premier plan. Il doit apparaître dans la liste des agents du cluster.

buildkite-agent start

Arrêtez-le avec Contrôle C. La formule Homebrew fournit une définition de service. Elle lance buildkite-agent start avec la config ci-dessus, redémarre en cas d’échec, et écrit dans le même fichier de log. Démarrez-la depuis le Terminal sur le bureau du Mac :

brew services start buildkite/buildkite/buildkite-agent@3
brew services list | grep buildkite

Sur macOS, l’agent tourne sous l’utilisateur qui a démarré le service launchd. Démarrez-le avec le compte qui possède Xcode et vos clés de signature.

Commencez avec un agent par Mac. Buildkite documente un réglage spawn dans le fichier de config, et une option --spawn, pour lancer plusieurs agents depuis un seul service. Deux builds Xcode simultanés se disputent les mêmes cœurs et la même mémoire. Sur une machine de 16 Go, mesurez d’abord un seul agent, puis essayez-en deux.

5. Faites-le survivre à un redémarrage

Les notes d’installation de la formule elle-même demandent de régler le Mac pour qu’il ouvre automatiquement la session de cet utilisateur. Le README du tap de Buildkite explique le compromis. Un LaunchAgent demande une session ouverte, mais il permet aux tests d’utiliser des outils graphiques comme le simulateur iOS. Activez la connexion automatique dans Réglages Système, sous Utilisateurs et groupes. Désactivez ensuite la veille, redémarrez, et vérifiez la liste des agents.

sudo pmset -a sleep 0
sudo shutdown -r now

Gardez le plist dans le dossier LaunchAgents de votre dossier personnel, là où Homebrew le place. Sur macOS 27, nous avons vu un plist dans /Library/LaunchAgents casser la connexion automatique. Voir la connexion automatique sur un Mac headless.

6. Une étape de pipeline pour le Mac

steps:
  - label: ":xcode: iOS tests"
    agents:
      queue: "macos"
    commands:
      - "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"
      - "ditto -c -k --keepParent build/TestResults.xcresult build/TestResults.xcresult.zip"
    artifact_paths:
      - "build/TestResults.xcresult.zip"
    timeout_in_minutes: 30
    retry:
      automatic:
        - exit_status: -1
          limit: 2

La relance sur exit_status: -1 vient de l’exemple d’étape de commande de Buildkite. Elle relance un job quand l’agent lui-même a été perdu, pas quand un test a échoué.

Erreurs courantes et solutions

• launchctl répond Could not find domain for. Buildkite indique qu’un utilisateur doit avoir une session ouverte sur le Mac. Ouvrez une session sur le bureau et rechargez le service.
• Refusing to load formula ... from untrusted tap. Lancez brew trust buildkite/buildkite et réinstallez.
• L’agent ne se connecte pas. Le token est faux, ou la clé de queue dans tags n’existe pas dans ce cluster.
• L’agent n’arrive pas à cloner. Mettez la clé dans ~/.ssh de l’utilisateur qui fait tourner l’agent.
• xcodebuild: error: Existing file at -resultBundlePath. Les builds réutilisent le checkout. Supprimez d’abord le bundle, comme ci-dessus.

Pour mettre à jour plus tard, lancez brew update && brew upgrade buildkite/buildkite/buildkite-agent@3.

Pourquoi un Mac dédié aide

Buildkite est conçu pour vos propres machines, et un Mac persistant garde ses caches. Dans notre benchmark sur l’app iOS Wikipedia avec Xcode 26.6, un job après un petit changement a pris 27 secondes sur un M6 déjà chaud. Un runner macos-26 neuf hébergé par GitHub a mis 269 secondes.

Quand les agents hébergés de Buildkite suffisent

Buildkite propose aussi des agents macOS hébergés. Vous les choisissez en créant une queue hébergée, selon sa documentation lue en octobre 2026. Si vous ne voulez aucune machine à gérer, c’est la voie la plus simple. MacRun est aussi le mauvais choix s’il vous faut un SLA, une IP fixe pour les règles de token, ou plus d’une région.

Pour le côté MacRun, voir les autres systèmes de CI. Pour ce qu’il faut lancer dans les étapes, voir le guide du pipeline CI/CD iOS.