Come eseguire un agente Buildkite su un Mac

Cosa ti serve prima

• Un cluster Buildkite, e il permesso di gestirne token degli agenti e code. Devi essere amministratore dell’organizzazione o maintainer del cluster.
• Un Mac con macOS 11 o successivo. È il minimo dichiarato da Buildkite. Apple silicon, Homebrew, Xcode e accesso amministratore.
• Una chiave SSH che l’agente può usare per clonare i tuoi repository.

1. Crea una coda e un token dell’agente

In Buildkite seleziona Agents per arrivare alla pagina Clusters e scegli il tuo cluster. Nella pagina Queues seleziona New Queue. Dalle la chiave macos e scegli Self hosted. Poi apri Agent Tokens, seleziona New Token, aggiungi una descrizione e crealo. Copia il valore. Buildkite lo mostra una sola volta.

Il modulo del token ha un campo Allowed IP Addresses. Su MacRun lascialo vuoto. I nostri Mac non hanno un IP pubblico statico, quindi una regola CIDR lascerebbe fuori l’agente.

2. Installa l’agente con Homebrew

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

Homebrew 7.0.7, la versione sul nostro Mac a ottobre 2026, rifiuta le formule di un tap di terzi finché non lo dichiari fidato. È la riga centrale. La formula ora si chiama buildkite-agent@3, e il vecchio nome nella documentazione di Buildkite punta ancora a lei.

Su Apple silicon i file finiscono sotto /opt/homebrew:

• Configurazione: /opt/homebrew/etc/buildkite-agent/buildkite-agent.cfg
• Hook: /opt/homebrew/etc/buildkite-agent/hooks
• Log: /opt/homebrew/var/log/buildkite-agent.log

Esegui brew info buildkite-agent per vedere i percorsi esatti sulla tua macchina.

3. Aggiungi il token e il tag della coda

La documentazione di Buildkite usa sed per sostituire il token segnaposto. Sostituisci il testo in maiuscolo con il tuo 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

Poi apri lo stesso file e imposta la riga dei tag, così l’agente entra nella tua coda:

tags="queue=macos"

Un agente appartiene a una sola coda self-hosted in un cluster. Senza tag di coda, entra nella coda predefinita. Se il cluster non ha una coda self-hosted predefinita, Buildkite dice che l’agente non riesce a collegarsi.

4. Provalo, poi avvialo come servizio

Avvialo una volta in primo piano. Dovrebbe comparire nell’elenco degli agenti del cluster.

buildkite-agent start

Fermalo con Control C. La formula Homebrew include la definizione di un servizio. Esegue buildkite-agent start con la configurazione qui sopra, riparte in caso di errore e scrive i log nello stesso file. Avvialo dal Terminale sul desktop del Mac:

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

Su macOS l’agente gira con l’utente che ha avviato il servizio launchd. Avvialo con l’account che possiede Xcode e le tue chiavi di firma.

Inizia con un agente per Mac. Buildkite documenta un’impostazione spawn nel file di configurazione, e un flag --spawn, per eseguire più agenti da un solo servizio. Due build Xcode insieme si contendono gli stessi core e la stessa memoria. Su una macchina da 16 GB misura prima un agente solo, poi provane due.

5. Fallo sopravvivere a un riavvio

Le note di installazione della formula dicono di impostare il Mac perché faccia il login automatico con questo utente. Il README del tap di Buildkite spiega il compromesso. Un LaunchAgent ha bisogno di un login, ma permette ai test di usare strumenti grafici come il simulatore iOS. Attiva il login automatico in Impostazioni di Sistema, in Utenti e gruppi. Poi disattiva lo stop, riavvia e controlla l’elenco degli agenti.

sudo pmset -a sleep 0
sudo shutdown -r now

Tieni il plist nella cartella LaunchAgents della tua home, che è dove lo mette Homebrew. Su macOS 27 abbiamo visto un plist in /Library/LaunchAgents bloccare il login automatico. Vedi login automatico su un Mac headless.

6. Uno step di pipeline per il 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

Il retry con exit_status: -1 viene dall’esempio di command step di Buildkite. Ripete un job quando si è perso l’agente stesso, non quando un test è fallito.

Errori comuni e soluzioni

• launchctl dice Could not find domain for. Buildkite dice che sul Mac deve esserci un utente connesso. Fai il login sul desktop e carica di nuovo il servizio.
• Refusing to load formula ... from untrusted tap. Esegui brew trust buildkite/buildkite e installa di nuovo.
• L’agente non si collega. Il token è sbagliato, oppure la chiave della coda nei tag non esiste in questo cluster.
• L’agente non riesce a clonare. Metti la chiave in ~/.ssh dell’utente che esegue l’agente.
• xcodebuild: error: Existing file at -resultBundlePath. Le build riusano il checkout. Cancella prima il bundle, come sopra.

Per aggiornarlo in seguito, esegui brew update && brew upgrade buildkite/buildkite/buildkite-agent@3.

Perché un Mac dedicato aiuta

Buildkite è pensato per le tue macchine, e un Mac persistente conserva le sue cache. Nel nostro benchmark sull’app iOS di Wikipedia con Xcode 26.6, un job dopo una piccola modifica ha richiesto 27 secondi su un M6 caldo. Un runner macos-26 nuovo ospitato da GitHub ha richiesto 269 secondi.

Quando bastano gli agenti in hosting di Buildkite

Buildkite offre anche agenti macOS in hosting. Li scegli quando crei una coda hosted, secondo la sua documentazione letta a ottobre 2026. Se non vuoi nessuna macchina da seguire, è la strada più semplice. MacRun è la scelta sbagliata anche se ti serve uno SLA, un IP statico per le regole del token, o più di una regione.

Per la parte MacRun, vedi altri sistemi di CI. Per cosa eseguire negli step, vedi la guida alla pipeline CI/CD iOS.