Einen Buildkite-Agent auf einem Mac betreiben

Was Sie vorher brauchen

• Einen Buildkite-Cluster und die Berechtigung, seine Agent-Tokens und Queues zu verwalten. Sie müssen Org-Admin oder Cluster-Maintainer sein.
• Einen Mac mit macOS 11 oder neuer. Das ist das Minimum, das Buildkite nennt. Dazu Apple Silicon, Homebrew, Xcode und Admin-Zugriff.
• Einen SSH-Schlüssel, mit dem der Agent Ihre Repositories klonen kann.

1. Queue und Agent-Token anlegen

Wählen Sie in Buildkite Agents, um zur Seite Clusters zu kommen, und wählen Sie Ihren Cluster. Wählen Sie auf der Seite Queues New Queue. Geben Sie ihr den Schlüssel macos und wählen Sie Self hosted. Öffnen Sie dann Agent Tokens, wählen Sie New Token, fügen Sie eine Beschreibung hinzu und legen Sie es an. Kopieren Sie den Wert. Buildkite zeigt ihn nur einmal an.

Das Token-Formular hat ein Feld Allowed IP Addresses. Lassen Sie es bei MacRun leer. Unsere Macs haben keine statische öffentliche IP, eine CIDR-Regel würde den Agent also aussperren.

2. Den Agent mit Homebrew installieren

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

Homebrew 7.0.7, die Version auf unserem Mac im Oktober 2026, lehnt Formeln aus dem Tap eines Dritten ab, solange Sie ihm nicht vertrauen. Dafür ist die mittlere Zeile da. Die Formel heißt jetzt buildkite-agent@3, und der alte Name aus der Doku von Buildkite verweist weiter darauf.

Auf Apple Silicon landen die Dateien unter /opt/homebrew:

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

Mit brew info buildkite-agent sehen Sie die genauen Pfade auf Ihrer Maschine.

3. Token und Queue-Tag eintragen

Die Doku von Buildkite ersetzt das Platzhalter-Token mit sed. Ersetzen Sie den Text in Großbuchstaben durch Ihr 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

Öffnen Sie dann dieselbe Datei und setzen Sie die tags-Zeile, damit der Agent Ihrer Queue beitritt:

tags="queue=macos"

Ein Agent gehört zu genau einer self-hosted Queue in einem Cluster. Ohne Queue-Tag tritt er der Standard-Queue bei. Hat der Cluster keine self-hosted Standard-Queue, kann sich der Agent laut Buildkite nicht verbinden.

4. Testen, dann als Dienst betreiben

Starten Sie ihn einmal im Vordergrund. Er sollte in der Agent-Liste des Clusters erscheinen.

buildkite-agent start

Beenden Sie ihn mit Control C. Die Homebrew-Formel bringt eine Dienstdefinition mit. Sie führt buildkite-agent start mit der Konfiguration von oben aus, startet bei Fehlern neu und schreibt in dieselbe Log-Datei. Starten Sie den Dienst im Terminal auf dem Desktop des Mac:

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

Unter macOS läuft der Agent als der Benutzer, der den launchd-Dienst gestartet hat. Starten Sie ihn mit dem Konto, dem Xcode und Ihre Signierschlüssel gehören.

Beginnen Sie mit einem Agent pro Mac. Buildkite dokumentiert eine Einstellung spawn in der Konfigurationsdatei und ein Flag --spawn, um mehrere Agents aus einem Dienst zu starten. Zwei Xcode-Builds gleichzeitig konkurrieren um dieselben Kerne und denselben Speicher. Messen Sie auf einer Maschine mit 16 GB erst einen einzelnen Agent, dann probieren Sie zwei.

5. Neustarts überstehen

Die Installationshinweise der Formel sagen, dass sich der Mac automatisch als dieser Benutzer anmelden soll. Das README des Taps von Buildkite erklärt den Kompromiss. Ein LaunchAgent braucht eine Anmeldung. Dafür können Tests GUI-Tools wie den iOS-Simulator nutzen. Schalten Sie die automatische Anmeldung in den Systemeinstellungen ein, unter Benutzer:innen & Gruppen. Schalten Sie dann den Ruhezustand ab, starten Sie neu und prüfen Sie die Agent-Liste.

sudo pmset -a sleep 0
sudo shutdown -r now

Lassen Sie die plist im Ordner LaunchAgents in Ihrem Home-Ordner. Dort legt Homebrew sie ab. Unter macOS 27 haben wir gesehen, dass eine plist in /Library/LaunchAgents die automatische Anmeldung verhindert. Siehe automatische Anmeldung auf einem Headless-Mac.

6. Ein Pipeline-Step für den 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

Der Retry mit exit_status: -1 stammt aus dem Beispiel von Buildkite für Command Steps. Er wiederholt einen Job, wenn der Agent selbst verloren ging, nicht wenn ein Test fehlschlug.

Häufige Fehler und Lösungen

• launchctl meldet Could not find domain for. Laut Buildkite muss ein Benutzer am Mac angemeldet sein. Melden Sie sich am Desktop an und laden Sie den Dienst erneut.
• Refusing to load formula ... from untrusted tap. Führen Sie brew trust buildkite/buildkite aus und installieren Sie erneut.
• Der Agent verbindet sich nicht. Das Token ist falsch, oder der Queue-Schlüssel in tags existiert in diesem Cluster nicht.
• Der Agent kann nicht klonen. Legen Sie den Schlüssel in ~/.ssh des Benutzers ab, der den Agent ausführt.
• xcodebuild: error: Existing file at -resultBundlePath. Builds nutzen den Checkout weiter. Löschen Sie zuerst das Bundle, wie oben.

Für ein späteres Upgrade führen Sie brew update && brew upgrade buildkite/buildkite/buildkite-agent@3 aus.

Warum ein dedizierter Mac hilft

Buildkite ist für Ihre eigenen Maschinen gebaut, und ein dauerhafter Mac behält seine Caches. In unserem Benchmark mit der Wikipedia-iOS-App und Xcode 26.6 dauerte ein Job nach einer kleinen Änderung auf einem warmen M6 27 Sekunden. Ein frischer gehosteter macos-26-Runner von GitHub brauchte 269 Sekunden.

Wann gehostete Agents von Buildkite reichen

Buildkite bietet auch gehostete macOS-Agents an. Laut der Doku, gelesen im Oktober 2026, wählen Sie sie beim Anlegen einer gehosteten Queue. Wollen Sie sich um gar keine Maschine kümmern, ist das der einfachere Weg. MacRun ist auch die falsche Wahl, wenn Sie ein SLA, eine statische IP für Token-Regeln oder mehr als eine Region brauchen.

Die Seite von MacRun finden Sie unter andere CI-Systeme. Was in die Steps gehört, steht im Leitfaden zur iOS-CI/CD-Pipeline.