Buildkite Agent auf Remote-Mac bereitstellen? 2026 Xcode 27 CI-Leitfaden

Stand 31.08.2026: Apple führt Xcode 27 in den offiziellen Release Notes als Beta-Werkzeugkette. Deshalb können Sie den Buildkite Agent auf einem Remote-Mac bereitstellen, sollten den Xcode-27-Knoten aber auf einem passenden Apple-Silicon-Mac isolieren und zunächst nur einen reproduzierbaren Kommandozeilen-Build zulassen. Simulator, Signierung und Neustart-Wiederherstellung folgen erst nach separater Prüfung. Apples Xcode-27-Beta-Release-Notes sind dabei die maßgebliche Referenz.

Für wen dieser Leitfaden gedacht ist:
Sie verlagern iOS- oder macOS-Builds aus der lokalen Entwicklungsumgebung in Buildkite und benötigen dafür einen dauerhaft erreichbaren Remote-Mac.
Sie betreiben als DevOps- oder Plattformverantwortlicher einen selbst verwalteten macOS-CI-Knoten oder testen Xcode 27 Beta, ohne die stabile Produktionsumgebung zu gefährden.

SECTION 01 Der Zeitplan für eine belastbare Bereitstellung

Ein Agent, der im Buildkite-Dashboard als „online“ erscheint, ist noch kein produktionsfähiger Buildknoten. Für die Entscheidung zählen beobachtbare Ergebnisse: Der richtige Rechner muss die richtige Queue bedienen, ein echtes Projekt muss mit dem festgelegten Xcode bauen, grafische Tests müssen eine verwertbare Ergebnisdatei erzeugen und der Knoten muss nach einem Neustart selbstständig wieder arbeitsfähig werden.

Planen Sie die Einführung deshalb als kontrollierte Abfolge:

Die entscheidende Grenze ist die Werkzeugkette: Xcode 27 bleibt nach der offiziellen Einordnung als Beta ein Testwerkzeug. Stabilitäts-, Laufzeit- oder Kompatibilitätsaussagen dürfen Sie daher nicht aus einem einzelnen erfolgreichen Lauf ableiten. Prüfen Sie die Systemanforderungen von Xcode sowie die jeweils aktuellen Hinweise in den Release Notes, bevor Sie den Rechner einer produktiven Queue zuweisen.

SECTION 02 Voraussetzungen und Isolationsgrenzen

Hardware und Betriebssystem

Für einen Xcode-27-Knoten sollte der Remote-Mac die von Apple dokumentierte Hardware- und Systemkombination erfüllen. In der Praxis bedeutet das: Apple Silicon, eine kompatible macOS-Version und eine Xcode-Installation, die nicht stillschweigend auf eine andere Version ausweicht. Wenn eine dieser Bedingungen nicht erfüllt ist, stoppen Sie die Einrichtung. Ein Agent, der zwar startet, aber mit einer falschen Architektur oder einem nicht passenden SDK arbeitet, erzeugt keine verlässliche CI-Basis.

Die Konfiguration darf nicht nur anhand des interaktiven Benutzerprofils beurteilt werden. Ein Agent kann unter einem eigenen macOS-Konto andere Suchpfade, Schlüsselbundrechte, Shell-Variablen und Homebrew-Pfade sehen als Sie in einer Terminal-Sitzung. Schreiben Sie daher den Xcode-Pfad in die Pipeline oder in eine ausdrücklich geladene Konfiguration. Verlassen Sie sich nicht auf xcode-select, das irgendwann manuell in einer grafischen Sitzung gesetzt wurde.

Verantwortlichkeiten der Komponenten

Buildkite übernimmt die Orchestrierung, die Pipeline-Definition und die Verteilung von Jobs. Der Agent-Prozess nimmt einen Auftrag an, führt ihn unter seinem lokalen macOS-Konto aus und meldet Status sowie Logs zurück. Der Remote-Mac stellt CPU, Arbeitsspeicher, Speicher, macOS, Xcode, Simulator-Runtimes und gegebenenfalls den Schlüsselbund bereit. Diese Trennung ist für die Fehlersuche wichtig: Eine erreichbare Steuerungsebene beweist nicht, dass der lokale Build-Kontext korrekt ist.

Nach der offiziellen Arbeitsweise selbst verwalteter Agents baut der Agent die Verbindung ausgehend auf. Öffnen Sie deshalb nicht vorsorglich eingehende Verwaltungsports für den Agenten. Für Wartung können SSH oder ein anderer sicherer Fernzugang erforderlich sein; dieser Zugang ist jedoch getrennt von der Buildkite-Verbindung zu behandeln. Dokumentieren Sie Firewall-Regeln, Benutzerrechte und den Fernzugriff so, dass ein späterer Administrator den Knoten ohne Umgehung der Sicherheitsvorgaben übernehmen kann. Die Buildkite-Dokumentation zu selbst verwalteten Agents beschreibt die grundlegende Betriebsweise.

Arbeitslasten getrennt bewerten

Ein Kommandozeilen-Build benötigt eine funktionierende Shell, Quellcodezugriff, SDKs und ausreichend Arbeitsbereich. Simulator- und UI-Tests benötigen zusätzlich eine geeignete grafische Sitzung und installierte Runtimes. Signierung und Veröffentlichung erweitern die Vertrauensgrenze um private Schlüssel, Profile und möglicherweise Zugang zu Auslieferungssystemen.

Behandeln Sie diese Arbeitslasten nicht als eine einzige Checkliste. Ein Knoten kann für Pull-Request-Kompilierung geeignet sein, während die Simulator-Sitzung nicht zuverlässig wiederhergestellt wird. Ebenso kann ein Release-Schritt zwar technisch funktionieren, aber aus Berechtigungsgründen nicht auf demselben Benutzerkonto laufen dürfen.

SECTION 03 Buildkite Agent auf einem Remote-Mac bereitstellen

Konto, Cluster und Queue

Legen Sie zunächst ein eigenes macOS-Konto für den Agenten an. Dieses Konto sollte nur die Verzeichnisse, Werkzeuge und Netzwerkzugriffe erhalten, die für die vorgesehenen Jobs notwendig sind. Verwenden Sie kein persönliches Administratorkonto als dauerhafte CI-Identität. Die Trennung erschwert zwar manche Erstkonfiguration, macht Logs, Schlüsselbundzugriffe und spätere Deaktivierung aber nachvollziehbar.

Ordnen Sie den Agenten einem ausdrücklich vorgesehenen Cluster und einer passenden Queue zu. Die offizielle Queue-Dokumentation von Buildkite ist die Referenz für diese Zuordnung. Benennen Sie Queue und Tags nach der Funktion, nicht nach einem temporären Rechnernamen, zum Beispiel mit einer Kennzeichnung für Xcode 27 Beta oder Simulator. So können Sie die Pipeline später auf einen stabilen Knoten zurückschalten, ohne jede Jobdefinition neu zu entwerfen.

Das Agent-Token bleibt ein Geheimnis. Setzen Sie in Beispielen, Shell-Kommandos und Dokumentationen ausschließlich Platzhalter:

export BUILDKITE_AGENT_TOKEN="<AGENT_TOKEN>"
export BUILDKITE_CLUSTER="<CLUSTER_NAME>"
export BUILDKITE_QUEUE="<QUEUE_NAME>"

Prüfen Sie vor dem Start, wo Konfiguration, Logdateien und Arbeitsverzeichnis tatsächlich liegen. Die Installationsanleitung für Buildkite Agent unter macOS sollte dabei Vorrang vor Blogbeiträgen oder Annahmen aus einer anderen macOS-Version haben. Halten Sie die effektive Konfiguration fest, nicht nur den Installationsbefehl.

Minimaler Diagnosejob

Der erste Job soll weder das vollständige Projekt bauen noch auf Signaturmaterial zugreifen. Lassen Sie nur die Informationen ausgeben, die die Node-Zuordnung und die Toolchain belegen:

set -u

printf 'Host: %s\n' "<HOST_PLACEHOLDER>"
uname -m
sw_vers
xcode-select -p
xcodebuild -version

Der Hostname bleibt in einer veröffentlichbaren Vorlage ein Platzhalter; in der internen Pipeline kann die tatsächliche Zuordnung über geschützte Agent-Metadaten geprüft werden. Wichtig ist, dass der Job auf keinem anderen Agenten landet. Wenn Queue oder Tags nicht eindeutig greifen, stoppen Sie und korrigieren die Pipeline-Routing-Regeln, bevor Quellcode oder Geheimnisse auf dem Knoten verarbeitet werden.

Für den Codezugriff verwenden Sie eine Maschinenidentität oder einen verwalteten Plattformschlüssel mit minimalem Leserecht. Buildkite beschreibt in der Dokumentation zum Codezugriff selbst verwalteter Agents, welche Zugriffswege in diesem Modell relevant sind. Hinterlegen Sie Repository-, Token- und Schlüsselwerte nicht direkt in einem frei lesbaren Skript. Sorgen Sie außerdem dafür, dass Fehlermeldungen keine vollständigen URLs mit Zugangsdaten ausgeben.

SECTION 04 Erstes Projekt und Xcode-27-Build

Reproduzierbare Umgebungsdefinition

Der erste reale Projektlauf beginnt erst, wenn der Diagnosejob die erwartete Architektur und Xcode-Version bestätigt. Definieren Sie dann den Xcode-Pfad explizit und prüfen Sie die Abhängigkeiten in derselben nicht interaktiven Umgebung, in der der Agent arbeitet. Eine Shell-Konfiguration, die nur bei einer manuellen Anmeldung geladen wird, darf nicht die einzige Quelle für PATH, Ruby-, Node- oder Swift-Werkzeuge sein.

Ein mögliches Pipeline-Muster mit Platzhaltern sieht so aus:

set -o pipefail

export DEVELOPER_DIR="<XCODE_27_DEVELOPER_DIR>"
export PROJECT_PATH="<PROJECT_OR_WORKSPACE_PATH>"
export SCHEME_NAME="<SCHEME_NAME>"
export DERIVED_DATA_PATH="<DERIVED_DATA_PATH>"

xcodebuild \
  -project "$PROJECT_PATH" \
  -scheme "$SCHEME_NAME" \
  -derivedDataPath "$DERIVED_DATA_PATH" \
  build test

Passen Sie die Parameter an das tatsächliche Projekt an. Verwenden Sie keinen frei erfundenen Pfad als Nachweis einer funktionierenden Installation. Der Nachweis besteht aus dem vom Projekt erwarteten Exit-Code, vollständigen Build-Logs, Testresultaten und einem definierten Artefaktpfad.

Nachweis statt Online-Status

Prüfen Sie die Schritte einzeln:

1. Klonen Sie das Repository mit der vorgesehenen Maschinenidentität in ein leeres Arbeitsverzeichnis.
2. Lösen Sie Swift-Package-, CocoaPods- oder andere Projektabhängigkeiten ohne interaktive Eingabe auf.
3. Bauen Sie das Projekt mit dem expliziten Xcode-27-Pfad.
4. Führen Sie die Unit-Tests aus und speichern Sie die erwarteten Resultatdateien.
5. Übergeben Sie ein klar benanntes Artefakt an die nächste Pipeline-Stufe.
6. Löschen Sie das temporäre Arbeitsverzeichnis erst nach gesicherter Log- und Artefaktübergabe.

Jeder Schritt muss einen beobachtbaren Fehlerzustand besitzen. Wenn die Abhängigkeitsauflösung einen Zugangsdialog öffnet, wenn ein Zertifikat angefordert wird oder wenn ein Pfad nur in Ihrer persönlichen Shell existiert, ist der Lauf nicht reproduzierbar. Notieren Sie Exit-Code, Xcode-Ausgabe und Artefaktpfad pro Stufe. Das erleichtert später die Unterscheidung zwischen einem Projektfehler, einem Agent-Problem und einer beschädigten Arbeitsumgebung.

SECTION 05 Simulator, Signierung und Parallelität

Grafische Sitzung und Simulator-Runtime

Ein reiner Buildknoten sollte keine grafische Sitzung erhalten, nur weil später eventuell UI-Tests geplant sind. Eine zusätzliche Sitzung bringt weitere Zustände: Benutzeranmeldung, Bildschirm- oder Sitzungszugriff, Simulator-Prozesse und Aufräumarbeiten. Wenn die Pipeline keine Simulator- oder UI-Aufgabe enthält, lassen Sie diese Komplexität weg.

Benötigt das Projekt Simulator-Tests, prüfen Sie zuerst, ob die passende Runtime installiert und für das Agent-Konto sichtbar ist. Starten Sie anschließend einen minimalen Test, der den Simulator öffnet, einen Testfall ausführt, Resultate sammelt und den Simulator wieder beendet. Die Pipeline muss auch nach einem fehlgeschlagenen Test aufräumen, sonst blockiert ein verwaister Prozess spätere Jobs.

Ein erfolgreicher Simulatorlauf beweist weder echte Gerätekompatibilität noch eine funktionierende Veröffentlichung. Hardwareabhängige Funktionen, Push-Benachrichtigungen, Kamera, Secure Enclave und Signaturabläufe benötigen jeweils eigene Abnahmen. Behandeln Sie Simulatorergebnisse daher als eine klar begrenzte CI-Stufe.

Signaturmaterial und Schlüsselbund

Trennen Sie normale Pull-Request-Builds von Signatur- und Veröffentlichungsaufgaben. Dafür kommen eigene Queues, ein separates Agent-Konto oder eine ausdrücklich geschützte Pipeline-Stufe infrage. Der gewöhnliche Build darf keine produktiven privaten Schlüssel sehen. Die Apple-Ressourcen zum Thema Code-Signierung helfen bei der Einordnung von Schlüsselbund- und Profilproblemen, ersetzen aber nicht Ihre eigene Freigabeprüfung.

Verwenden Sie in Dokumentation und Beispielen ausschließlich Platzhalter:

Certificate: <CERTIFICATE_NAME>
Team ID: <TEAM_ID>
Provisioning profile: <PROFILE_IDENTIFIER>
Keychain password: <KEYCHAIN_SECRET>

Prüfen Sie im nicht interaktiven Agent-Lauf, ob der Schlüsselbund entsperrt werden darf, ob der private Schlüssel dem vorgesehenen Prozess zugänglich ist und ob das Provisioning Profile zum Ziel passt. Eine lokal funktionierende Signierung in einer geöffneten Benutzeroberfläche ist kein Beweis für einen automatisierten Release-Schritt.

Konfiguration, Kosten und Risiko

Bei einer Entscheidung für einen Remote-Mac sollten Sie nicht nur den Mietpreis betrachten. Die relevanten Kostenpositionen unterscheiden sich je nach Arbeitslast:

Vergleichen Sie Lösungen deshalb anhand des Betriebsmodells:

VPSNIX kann dabei als Remote-Mac-Mietlösung in Ihren Vergleich einbezogen werden, sofern die benötigte Apple-Silicon-Konfiguration, der gewünschte Zeitraum und der Fernzugriff zu Ihrem Prüfplan passen. Entscheidend bleibt, dass Sie Xcode 27 zunächst in einer isolierten Queue validieren, statt einen stabilen Produktionsknoten zu ersetzen.

Achtung: Löschen Sie DerivedData, Schlüsselbunde oder Agent-Verzeichnisse nicht als ersten Reparaturschritt. Sichern Sie Logs und definieren Sie vorher den Wiederherstellungspfad; eine Bereinigung kann Beweise für einen Berechtigungs- oder Toolchainfehler entfernen.

SECTION 06 Neustart, launchd und Betriebsfreigabe

Automatischer Agent-Start

Für einen dauerhaft erreichbaren Knoten muss der Agent als launchd-Dienst eingerichtet werden. Die Konfiguration sollte das vorgesehene Benutzerkonto, die tatsächlichen Pfade, die Umgebungsvariablen und die Logziele eindeutig festlegen. Die Apple-Dokumentation zu launchd-Jobs ist die maßgebliche Grundlage für den Startmechanismus.

Vermeiden Sie eine Konfiguration, die nur nach manueller Anmeldung funktioniert, wenn der Knoten unbeaufsichtigte Builds ausführen soll. Für grafische Simulator-Tests müssen Sie zusätzlich klären, ob die benötigte Benutzersitzung nach dem Neustart vorhanden ist. Ein automatisch gestarteter Agent ohne zugängliche Simulator-Umgebung kann für Kommandozeilenjobs online erscheinen und grafische Aufgaben trotzdem nicht ausführen.

Kontrollierter Wiederanlauf

Führen Sie den Test in einer Wartungsphase durch und prüfen Sie die Zustände nacheinander:

1. Sichern Sie den letzten Agent-Log, den Pipeline-Status und offene Arbeitsverzeichnisse.
2. Stoppen Sie laufende Jobs kontrolliert und kennzeichnen Sie den Knoten in Buildkite als nicht verfügbar.
3. Starten Sie den Remote-Mac über den vorgesehenen Wartungsweg neu.
4. Prüfen Sie den Fernzugriff und die Benutzer- beziehungsweise Grafiksitzung.
5. Kontrollieren Sie den launchd-Status und den Agent-Log.
6. Warten Sie auf die korrekte Queue-Zuordnung.
7. Führen Sie einen echten Diagnose- und anschließend einen kleinen Projekt-Build aus.
8. Wiederholen Sie bei Bedarf den Simulator- oder Signaturtest getrennt.

Wenn nur der Prozess läuft, aber die Queue nicht erreichbar ist, gilt der Test als fehlgeschlagen. Gleiches gilt für einen online gemeldeten Agenten, dessen Xcode-Pfad, Schlüsselbund oder Arbeitsverzeichnis nach dem Neustart nicht stimmt. Halten Sie einen stabilen Werkzeugkettenknoten als Rückfalloption bereit und fixieren Sie die Xcode-Version in der Produktionspipeline, solange die Beta-Umgebung noch bewertet wird.

SECTION 07 Freigabe-Checkliste für den Remote-Mac

Führen Sie diese Prüfung vor der Zuordnung zur produktiven Queue vollständig durch:

• [ ] Apple-Silicon-Architektur und macOS-Version entsprechen den aktuellen Apple-Anforderungen.
• [ ] Xcode 27 ist ausdrücklich als Beta-Werkzeugkette gekennzeichnet und vom stabilen Produktionsknoten getrennt.
• [ ] Das Agent-Konto ist ein eigenes, möglichst niedrig privilegiertes macOS-Konto.
• [ ] Agent-Token, Queue, Cluster und Repository-Zugriff werden nicht in Logs oder Beispielen offengelegt.
• [ ] Ein Diagnosejob landet ausschließlich auf dem vorgesehenen Remote-Mac.
• [ ] Der Xcode-Pfad wird im Agent-Kontext explizit gesetzt.
• [ ] Abhängigkeiten werden ohne interaktive Shell oder Dialog aufgelöst.
• [ ] Ein echtes Projekt kompiliert, testet und erzeugt die erwarteten Resultatdateien.
• [ ] Simulator-Runtime, grafische Sitzung, Testausführung und Bereinigung wurden separat geprüft.
• [ ] Signaturzertifikate und private Schlüssel sind von gewöhnlichen Buildjobs getrennt.
• [ ] Parallelität wurde mit dem tatsächlichen Projekt geprüft; bei Workspace-, Simulator- oder Schlüsselbundkonflikten bleibt die Ausführung seriell.
• [ ] launchd startet den Agenten nach einem kontrollierten Neustart.
• [ ] Queue-Verbindung und echter Build funktionieren nach dem Neustart.
• [ ] Logs, Arbeitsverzeichnisse, Speicherwachstum und Xcode-Update-Verantwortung sind dokumentiert.
• [ ] Ein stabiler Rückfallknoten bleibt verfügbar, solange Xcode 27 Beta eingesetzt wird.

Mit dieser Liste können Sie den Knoten in vier Zustände einteilen: für Kommandozeilen-Builds freigegeben, für Simulator-Aufgaben freigegeben, für Signierungsaufgaben freigegeben oder noch nicht produktionsbereit. Diese abgestufte Freigabe ist belastbarer als ein einzelner „Agent online“-Indikator.

SECTION 08 Häufige Fragen

Die folgenden Antworten decken die typischen Suchabsichten rund um Buildkite self-hosted agent, Xcode 27 und macOS CI ab, ohne Beta-Verhalten als dauerhaft garantiert darzustellen.

Installation auf einem Remote-Mac

Ja, der Buildkite Agent kann auf einem Remote-Mac installiert werden. Der richtige Einstieg ist ein eigenes Benutzerkonto mit minimalen Rechten, nicht die sofortige Einrichtung eines Release-Arbeitsplatzes. Verwenden Sie die offizielle macOS-Installationsanleitung, registrieren Sie den Agenten mit einem geschützten Token und testen Sie danach die Queue-Zuordnung mit einem Diagnosejob. Erst anschließend sollte das Repository eingebunden werden.

Xcode-27-Queue

Für Xcode 27 benötigen Sie eine eindeutig markierte Queue oder Agent-Tags, die nicht auf stabile Knoten passen. Der Pipeline-Schritt muss diese Kennzeichnung aktiv anfordern. Geben Sie im Diagnosejob Architektur, macOS-Version, xcode-select-Pfad und xcodebuild -version aus. So erkennen Sie, ob die Pipeline wirklich den Beta-Knoten verwendet oder versehentlich auf einem anderen Agenten läuft.

Wiederanlauf nach Neustart

Die automatische Wiederanmeldung hängt nicht allein vom Agent-Prozess ab. launchd muss den Dienst nach dem Neustart laden, das Agent-Konto muss die benötigte Umgebung erhalten und die Queue-Verbindung muss wiederhergestellt werden. Bei Simulatoraufgaben kommt die grafische Sitzung hinzu. Testen Sie deshalb nach dem Neustart zuerst den Fernzugriff, danach den Agent-Status und zuletzt einen echten Build mit Artefakt.

iOS-Simulator im selbst verwalteten Agent

Ein selbst verwalteter Mac kann iOS-Simulator-Tests ausführen, wenn die passende Runtime installiert ist und die Sitzung des Agent-Kontos grafische Aufgaben zulässt. Prüfen Sie Start, Test, Ergebnisexport und Bereinigung in einem kleinen Projekt. Ein grüner Simulatorjob ist jedoch nur ein Teilnachweis: Er bestätigt keine echte Gerätehardware, keine Produktionssignierung und keine Veröffentlichung.

Isolierte Apple-Signierung

Für die Signierung sollte der Agent nicht dieselben Rechte wie ein gewöhnlicher Pull-Request-Knoten besitzen. Verwenden Sie eine getrennte Queue, ein getrenntes Konto oder eine geschützte Stufe mit streng begrenztem Schlüsselbundzugriff. Zertifikatsnamen, Team-ID, Profile und Geheimnisse bleiben Platzhalter in Dokumentation und Beispielen. Der Release-Schritt muss vollständig nicht interaktiv und auditierbar laufen.

Die Alternative zum aktuellen Aufbau verdient eine nüchterne Prüfung: Ein lokaler Mac verursacht Anschaffungs-, Wartungs- und Ausfallbindung; ein geteilter stabiler Knoten erschwert die sichere Erprobung einer Beta-Werkzeugkette; eine virtuelle Umgebung kann bei Simulator, Signierung oder Hardwarezugriff an Grenzen stoßen. Wenn Sie keinen dauerhaft erreichbaren Apple-Silicon-Mac für eine getrennte Queue besitzen, ist die Miete eines Remote-Mac von VPSNIX für die Validierungsphase meist der kontrollierbarere Weg: Sie können die Xcode-27-Pipeline isoliert prüfen, ohne Produktionshardware umzubauen, sollten aber weiterhin Ihre eigenen Build-, Simulator-, Signatur- und Neustartnachweise erbringen.

Wenn diese Nachweise vollständig sind, ordnen Sie den Knoten entweder nur der vorgesehenen Beta-Queue oder zusätzlich den freigegebenen Produktionsaufgaben zu. Für eine zeitlich begrenzte Validierung können Sie die passende VPSNIX-Bestelloption prüfen; für langfristig konstante Hochlast oder zwingenden physischen Gerätezugriff bleibt eigene Hardware die ehrlichere Wahl.

SECTION 09 FAQ