Befund: Die Agent Workflow Firewall benötigt Container-Aufträge; GitHub Agentic Workflows unterstützt deshalb keine macOS-Runner für Agent-Aufträge (offizielle FAQ).
Schnellster Weg: Lassen Sie den Agenten auf einem unterstützten Linux-Runner arbeiten und führen Sie Xcode anschließend in einem separaten, regulären GitHub-Actions-Auftrag auf macOS aus.
Dieser Leitfaden ist für Sie, wenn Sie mit gh-aw Repository-Aufgaben automatisieren und klären müssen, ob diese Aufgaben Xcode einschließen können.
Er hilft Ihnen, wenn Sie Apple-Plattform-Builds betreiben und Agent-Ergebnisse sicher an Mac-CI übergeben möchten.
Auch als Verantwortliche oder Verantwortlicher für die Entwicklungsplattform finden Sie hier Prüfschritte für Auslöser, Artefakte und Berechtigungen.
Zuletzt geprüft am 25.10.2026 anhand der GitHub-Agentic-Workflows-Dokumentation und der GitHub-Actions-Dokumentation zu Workflow-Ereignissen.
SECTION 01Warum kann GitHub Agentic Workflows Xcode nicht direkt auf einem Mac-Runner ausführen?
Die Grenze betrifft den Agent-Auftrag, nicht jede GitHub-Actions-Ausführung unter macOS. Laut offizieller Dokumentation ist die für Agent-Aufträge erforderliche Agent Workflow Firewall auf Container-Aufträge angewiesen, die auf macOS-Runnern nicht ausgeführt werden können. GitHub empfiehlt deshalb, macOS-spezifische Werkzeuge in einen separaten, regulären GitHub-Actions-Auftrag auszulagern (FAQ).
Das ist für die Architektur entscheidend: gh-aw-Agent-Auftrag, gewöhnlicher GitHub-Actions-Auftrag und Xcode-Toolchain sind drei verschiedene Dinge. Ein Workflow, der mit gh-aw definiert und von dessen Agenten ausgeführt wird, ist nicht gleichbedeutend mit einem gewöhnlichen Actions-Workflow. Xcode benötigt für Build und Tests eine macOS-Ausführungsumgebung; daraus folgt aber nicht, dass der Agent-Auftrag selbst auf diesen Mac-Runner gehört.
Verwechseln Sie außerdem nicht die Plattform, auf der Sie ein gh-aw-CLI installieren oder einen Workflow vorbereiten, mit der Plattform, auf der der Agent-Auftrag ausgeführt wird. Die Installation eines Werkzeugs auf macOS hebt die dokumentierte Runner-Einschränkung nicht auf. Maßgeblich sind der Ausführungstyp des Auftrags und die von gh-aw benötigte Firewall-Konfiguration. Prüfen Sie dafür die Dokumentation zum Ablauf der Agent-Workflows.
Warum wird macOS für Agent-Aufträge nicht unterstützt?
Weil die benötigte Firewall Container-Aufträge voraussetzt und die erforderliche Container-Ausführung auf macOS-Runnern nicht verfügbar ist. Die praktikable Alternative ist keine Umgehung dieser Grenze, sondern eine Trennung: Agent-Aufgabe unter Linux, Xcode-Build in einem unabhängigen Actions-Auftrag auf macOS.
Im Alltag sind dabei meist drei übersehene Risiken relevanter als die Workflow-Syntax:
- Falsche Zuständigkeit: Ein Agent kann Änderungen vorschlagen oder Dateien erzeugen, aber der Xcode-Auftrag muss selbst klar festlegen, welche Revision er baut.
- Unklare Übergabe: Ein Artefaktname allein belegt nicht, zu welchem Commit und zu welchem Lauf die Datei gehört.
- Zu weitreichende Berechtigungen: Ein späterer Workflow kann mit anderen Berechtigungen oder Geheimnissen laufen als der auslösende Auftrag. Prüfen Sie deshalb nicht nur den Trigger, sondern auch das Vertrauen in den ausgeführten Code.
SECTION 02Vor dem ersten Lauf: Eingaben, Zuständigkeiten und Rückgabewerte festlegen
Bevor Sie gh-aw mit Xcode CI verbinden, definieren Sie die Schnittstelle zwischen beiden Abläufen. Sonst entsteht ein erfolgreicher Agent-Lauf, dessen Ausgabe sich nicht zuverlässig einem Build zuordnen lässt.
Legen Sie für die Agent-Seite fest, welche Repository-Aufgaben zulässig sind: etwa Dateien analysieren, einen Änderungsvorschlag erzeugen oder eine klar begrenzte Änderung auf einem Arbeitszweig vorbereiten. Xcode-Build, Simulator-Tests, Signierung und das Erzeugen Apple-spezifischer Build-Artefakte gehören dagegen in den regulären macOS-Auftrag.
Vereinbaren Sie anschließend die Übergabedaten. Mindestens sollten diese Informationen nachvollziehbar sein:
- Commit-SHA: Welche konkrete Revision soll der Mac-Auftrag auschecken und bauen?
- Arbeitszweig: Ist die Änderung auf dem erwarteten Zweig entstanden, oder stammt sie aus einem anderen Kontext?
- Auslöser: Wird der Mac-Auftrag im selben Workflow oder nach Abschluss eines separaten Workflows gestartet?
- Artefakte: Welche Dateien werden übergeben, und welchem Lauf sind sie zugeordnet?
- Ergebnis: Welche Build- und Testergebnisse gelten als Erfolg, und wie wird ein Fehler an den Gesamtprozess zurückgemeldet?
Eine konkrete Ausgangslage: Ein Agent erstellt eine Änderung an einer Swift-Datei. Der Agent-Lauf ist erfolgreich, doch der Mac-Auftrag baut später den aktuellen Standardzweig statt der Agent-Revision. Der Build kann dann grün sein, ohne die Änderung überhaupt geprüft zu haben. Binden Sie daher SHA und Zweig als verbindliche Eingaben ein, statt sie nur in Protokollen zu erwähnen.
Hinweis: Eine Agent-Ausgabe ist nicht automatisch ein vertrauenswürdiger Build-Auftrag. Behandeln Sie Änderungen aus externen Pull Requests oder anderen nicht vertrauenswürdigen Quellen zunächst als Code, der keine Signier-Geheimnisse oder Schreibrechte erhalten darf. Die Sicherheitshinweise für GitHub Actions erläutern die Risiken und Schutzmaßnahmen.
SECTION 03Erster Probelauf: gh-aw unter Linux ohne Xcode verifizieren
Validieren Sie zunächst die Agent-Seite, ohne gleichzeitig Xcode-Fehler, Signierung und Runner-Konfiguration zu untersuchen. So lässt sich ein Problem einer konkreten Phase zuordnen.
- Workflow-Definition prüfen. Kontrollieren Sie die gh-aw-spezifischen Angaben und die in Ihrem Repository geltenden Trigger. Die Frontmatter-Konfiguration muss zu den vorgesehenen Runner- und Workflow-Angaben passen. Stellen Sie sicher, dass die Agent-Ausführung auf einer unterstützten Plattform vorgesehen ist.
- Generierte Dateien überprüfen. Folgen Sie dem offiziellen gh-aw-Ablauf für Ihre Workflow-Definition und kontrollieren Sie die daraus erzeugten beziehungsweise eingecheckten Dateien. Verlassen Sie sich nicht auf eine lokal erfolgreiche Bearbeitung, wenn die Repository-Version eine andere Konfiguration enthält.
- Agent-Engine und Authentifizierung festlegen. Prüfen Sie, welche Engine Ihr Workflow verwenden soll und welche Zugangsdaten dafür nötig sind. Hinterlegen Sie Geheimnisse nicht in Dateien, die der Agent bearbeiten oder als Artefakt ausgeben kann.
- Eine harmlose Aufgabe ausführen. Lassen Sie zuerst einen eng begrenzten Repository-Auftrag laufen, der weder Xcode noch Signierung erfordert. Prüfen Sie Trigger, Agent-Ausgabe, Laufstatus und die tatsächlich erteilten Berechtigungen.
- Ausgangsdaten sichern. Erfassen Sie den Lauf, den Commit-SHA, den Zweig und die Agent-Ausgabe. Diese Werte bilden später die Referenz, mit der Sie den Mac-Build abgleichen.
Der Zweck dieses Probelaufs ist nicht, einen Xcode-Build zu simulieren. Er zeigt, dass Agent-Auftrag und Repository-Übergabe wie erwartet funktionieren, bevor Sie den zweiten Ausführungspfad ergänzen.
Was ist der Unterschied zwischen gh-aw und einem macOS-Workflow in GitHub Actions?
gh-aw steuert Agent-Aufträge und deren Einschränkungen. Ein regulärer GitHub-Actions-Workflow kann dagegen als separater Auftrag für macOS-spezifische Werkzeuge konfiguriert werden. Dass ein Repository beide Workflow-Arten enthält, macht sie nicht zu demselben Auftrag; kennzeichnen Sie ihre Zuständigkeiten in Konfiguration und Betriebsdokumentation eindeutig.
SECTION 04Xcode-Aufträge anbinden: gleicher Workflow oder workflow_run
Für den Mac-Teil erstellen Sie einen gewöhnlichen GitHub-Actions-Workflow, der auf einem macOS-Runner Xcode-Build und Tests ausführt. Beschreiben Sie ihn nicht als gh-aw-Agent-Auftrag. Als Einstieg haben Sie zwei Muster: Abhängigkeiten innerhalb eines Workflows oder eine Übergabe an einen nachgelagerten Workflow.
Gleicher Workflow mit Abhängigkeiten: Verwenden Sie dieses Muster, wenn Agent- und Mac-Auftrag in Ihrem Ablauf zusammengefasst werden können und die Eingaben leicht an eine definierte Revision gebunden bleiben. Mit einer Abhängigkeitsbeziehung kann der Mac-Auftrag auf den Abschluss eines vorherigen Auftrags warten. Halten Sie trotzdem ausdrücklich fest, welche Revision gebaut wird und welche Dateien übergeben werden.
Nachgelagerter Workflow über workflow_run: Das Ereignis workflow_run startet einen weiteren Workflow, wenn ein passender vorgelagerter Workflow abgeschlossen ist. GitHub dokumentiert, dass der nachgelagerte Workflow im Standardzweig vorhanden sein muss; außerdem sind Ausführungskontext und Berechtigungen gesondert zu prüfen (Dokumentation zu Workflow-Ereignissen). Ein erfolgreicher Trigger beweist nicht automatisch, dass der nachgelagerte Lauf den passenden Commit verwendet.
Wie übergeben Sie die Aufgabe vom Agenten an den Xcode-Build?
Machen Sie den Auslöser explizit und geben Sie dem Mac-Auftrag eine prüfbare Referenz auf die Agent-Ausführung. Bei workflow_run müssen Sie den passenden Workflow identifizieren und die Upstream-Ausführung, den Zweig, den Commit und deren Ergebnis kontrollieren. Erst dann laden Sie gegebenenfalls Artefakte aus genau diesem Lauf herunter und starten den Build auf der zugehörigen Revision.
Legen Sie außerdem fest, wie ein fehlgeschlagener Build den Gesamtstatus beeinflusst. Wenn der Xcode-Auftrag scheitert, darf der Gesamtprozess nicht so aussehen, als sei die Agent-Aufgabe vollständig und erfolgreich abgenommen. Verknüpfen Sie Build-Ergebnis und Agent-Lauf durch Lauf-ID, SHA und nachvollziehbare Protokolle.
SECTION 05Artefakte und Rechte: Übergabe prüfen statt nur Dateien kopieren
Innerhalb eines Workflows können Actions-Artefakte zur Speicherung und zum Austausch von Dateien zwischen Aufträgen dienen. GitHub beschreibt die dafür vorgesehenen Mechanismen in der Dokumentation zum Speichern und Teilen von Workflow-Daten. Bei einem separaten workflow_run-Ablauf müssen Sie dagegen sicherstellen, dass der Download aus der gewünschten vorgelagerten Ausführung stammt. Die Dokumentation von download-artifact beschreibt die dafür relevanten Parameter, darunter die Zuordnung zu einem anderen Lauf.
Wie übertragen gh-aw und der macOS-Workflow Build-Artefakte?
Wenn beide Aufträge im selben Workflow liegen, können Sie Dateien über Actions-Artefakte austauschen. Bei einer workflowübergreifenden Übergabe geben Sie den Bezug zum konkreten Lauf an und validieren danach Commit-SHA, Zweig und Laufstatus. Ein Artefakt sollte nicht allein anhand seines Namens akzeptiert werden: Name und Inhalt beweisen weder Herkunft noch Vertrauenswürdigkeit.
Achten Sie bei einem nachgelagerten Workflow besonders auf die Berechtigungsgrenze. GitHub weist darauf hin, dass workflow_run-Folgeworkflows Zugriff auf Geheimnisse und ein schreibberechtigtes Token erhalten können, selbst wenn der vorgelagerte Workflow diese Rechte nicht hatte. Dieser Kontext macht es riskant, nicht vertrauenswürdigen Code ungeprüft im Folgeworkflow auszuführen oder ihm Zugang zu Signiermaterial zu geben. Grenzen Sie permissions so eng wie möglich ein, prüfen Sie den Ursprung der Änderung und trennen Sie die Build-Validierung von Aktionen, die ein Artefakt veröffentlichen oder signieren.
Wie kontrollieren Sie bei workflow_run den vorgelagerten Commit?
Lesen Sie die Angaben zur vorgelagerten Ausführung aus dem Ereigniskontext aus und gleichen Sie deren SHA und Zweig mit der erwarteten Änderung ab. Prüfen Sie zusätzlich den Namen des auslösenden Workflows und dessen Abschlussstatus. Laden Sie nur das Artefakt aus der identifizierten Ausführung und lassen Sie den Mac-Auftrag genau die Revision bauen, die Sie zuvor als Eingabe freigegeben haben. Wenn einer dieser Werte nicht zusammenpasst, brechen Sie ab, statt auf den neuesten Zweigstand zurückzufallen.
| Übergabemuster | Geeignet, wenn | Prüfung vor dem Xcode-Auftrag | Typische Schwäche |
|---|---|---|---|
| Abhängige Aufträge im selben Workflow | Agent- und Mac-Auftrag eine gemeinsame Ausführung nutzen können | SHA, Job-Abhängigkeit und Artefaktquelle | Unklare Übergabe, wenn der Mac-Auftrag eine andere Revision auscheckt |
workflow_run |
Agent- und Mac-Ablauf unabhängig bleiben sollen | Workflow-Name, Zweig, SHA, Abschlussstatus und Lauf-ID | Folgeworkflow kann weitergehende Berechtigungen erhalten |
| Nur regulärer Mac-CI-Auftrag | Agent-Ergebnis für den Build nicht benötigt wird | Build-Revision und gewöhnliche CI-Regeln | Agent-Automatisierung wird nicht mit dem Build-Ergebnis gekoppelt |
| Artefaktweg | Was Sie verifizieren | Abbruchbedingung |
|---|---|---|
| Austausch zwischen Aufträgen in einem Workflow | Quelldatei, Artefaktbezug und auslösender Commit | Datei stammt nicht aus der erwarteten Abhängigkeit |
| Download aus einem früheren Workflow-Lauf | Lauf-ID, SHA, Zweig und Abschlussstatus | Metadaten widersprechen der erwarteten Upstream-Ausführung |
| Kein Artefaktaustausch | Der Mac-Auftrag checkt die freigegebene Revision selbst aus | SHA oder Checkout-Zweig weicht von der Freigabe ab |
SECTION 06Abnahme: mit einem vollständigen Lauf über Freigabe oder Isolation entscheiden
Schalten Sie die Verbindung nicht allein deshalb produktiv, weil beide Einzelworkflows grün sind. Führen Sie einen vollständigen Durchlauf aus: Agent-Auftrag, Übergabe, Xcode-Build, Tests und Rückmeldung des Ergebnisses an den Gesamtprozess. Prüfen Sie dabei nicht nur den Erfolgspfad, sondern auch, was bei einer falschen SHA, einem fehlenden Artefakt, einem fehlgeschlagenen Test oder einem nicht vertrauenswürdigen Beitrag geschieht.
| Ergebnis der Abnahme | Entscheidung | Nächster Schritt |
|---|---|---|
| Agent-Ausgabe, SHA, Artefakt und Xcode-Ergebnis sind eindeutig verknüpft; Rechte sind begrenzt | Linux-Agent plus separater Mac-CI-Auftrag verwenden | Fehlersignale und Protokollzuordnung in den Regelbetrieb übernehmen |
| Agent-Aufgabe bringt für den Build keinen nachweisbaren Nutzen | Nur reguläre Mac-CI beibehalten | Agent-Workflow nicht in den Build-Pfad einbeziehen |
| Commit-Zuordnung oder Sicherheitsprüfung ist unklar | Getrennt und eingeschränkt weiter testen | Keine Geheimnisse oder Schreibrechte an den unsicheren Pfad geben |
Eine produktive Freigabe setzt voraus, dass ein Fehler im Xcode-Auftrag als Fehler des Gesamtprozesses sichtbar wird und dass ein Artefakt eindeutig zu einem geprüften Commit gehört. Fehlt eines dieser Kriterien, halten Sie den Ablauf isoliert. Erst wenn Wiederholungsläufe dieselben Zuordnungen und Sicherheitsgrenzen bestätigen, sollten Sie die Übergabe für reguläre Builds freigeben.
Wann ist eine weitere Mac-Ausführungsumgebung sinnvoll?
Erst dann, wenn Ihr Agent unter Linux bereits stabil arbeitet, aber der reguläre Xcode-Auftrag eine passende macOS-Ausführungsebene benötigt. Ein zusätzliches Ausführungsmodell löst weder eine fehlerhafte Commit-Zuordnung noch zu weit gefasste Rechte. Prüfen Sie vor einer Entscheidung, welche Xcode- und Testwerkzeuge Ihr Projekt benötigt, wie Sie den Mac-Auftrag anbinden und ob die tatsächliche Umgebung diese Anforderungen erfüllt. Die Übersicht zu MACNOX und die Angaben zu den Mietkosten können Sie für diese Prüfung heranziehen; schließen Sie daraus keine nicht bestätigte Runner-Funktion oder Toolchain-Unterstützung ab.
Wenn Ihr bisheriger Ablauf Xcode auf Entwicklerrechnern verteilt, einen Agenten fälschlich auf macOS starten soll oder Artefakte ohne eindeutige SHA-Zuordnung weiterreicht, entstehen vermeidbare Wartungs- und Sicherheitsrisiken. Für einen vorübergehenden Xcode-Test oder eine zusätzliche Ausführungsumgebung kann ein gemieteter Mac von MACNOX eine Alternative zum sofortigen Hardwarekauf sein. Prüfen Sie vorab die konkrete Zugangsart, die für Ihr Projekt erforderliche Toolchain und den geplanten Übergabeweg; für dauerhaft hohe Last oder Anforderungen an physische Anschlüsse kann ein eigener Mac besser passen. Die Mietoptionen von MACNOX sollten Sie erst bewerten, wenn diese Abnahmekriterien feststehen.