Claude Code hat den Code geändert, aber der allgemeine Runner kann keine Apple-Toolchain ausführen.

Die schnellste Lösung ist eine Trennung in zwei Jobs: Claude Code bearbeitet Issue oder Pull Request, ein kontrollierter Remote-Mac übernimmt danach Xcode-Build und Tests. Signierte Releases bleiben auf einem unabhängigen Runner mit minimalen Rechten und manueller Freigabe.

Für wen dieser Leitfaden gedacht ist: Sie entwickeln iOS- oder macOS-Projekte und möchten Änderungen aus GitHub Issues oder Pull Requests automatisch prüfen. Sie betreiben einen selbst gehosteten Mac-Runner, planen Routing und Neustart-Wiederherstellung oder müssen als Plattform- und Sicherheitsverantwortlicher Zugriffe auf Quellcode, Netzwerk, Schlüsselbund und Veröffentlichungsdaten begrenzen.

Zuletzt aktualisiert am 07.09.2026. Die Aussagen wurden anhand der offiziellen Dokumentation zu Claude Code Action, GitHub Actions Runnern und Apple Xcode geprüft.

Grundarchitektur für Agent und Validierung

Claude Code Action, Claude Code CLI, GitHub Actions Runner und Xcode sind vier getrennte Ebenen. Eine saubere Pipeline behandelt sie nicht als ein gemeinsames Programm:

  1. Agent-Job: Claude Code liest den erlaubten Kontext, analysiert die Aufgabe, ändert Dateien und erstellt einen Commit oder einen überprüfbaren Patch.
  2. Übergabe: Der Workflow schreibt den tatsächlich erzeugten Commit-SHA als Ausgabe oder Artefakt fest.
  3. Mac-Validierungsjob: Ein selbst gehosteter Mac-Runner holt genau diesen SHA, prüft das Projekt und führt Xcode-Kommandos aus.
  4. Rückgabe: Buildstatus, Testresultate und strukturierte Logs gehen zurück in den Pull Request oder in einen nachgelagerten Review-Schritt.

Die Trennung verhindert einen häufigen Fehler: Der Mac-Job baut nicht automatisch den neuesten Stand eines Branches, sondern den unveränderlichen Commit, den der Agent tatsächlich erzeugt hat. Ohne diese Bindung kann ein späterer Push die geprüfte Version austauschen.

Die offizielle Claude-Code-Action-Anleitung beschreibt die Verwendung des Actions-Workflows. Die Sicherheitshinweise zur Action sollten Sie vor der Freigabe des Agent-Jobs gemeinsam mit der GitHub-Dokumentation zur sicheren Nutzung von Actions durchgehen.

Beispielhafte Übergabe mit Platzhaltern

jobs:
  agent:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    outputs:
      validated_sha: ${{ steps.commit.outputs.sha }}
    steps:
      - uses: actions/checkout@<ACTION_VERSION>
      - name: Claude Code
        uses: anthropics/claude-code-action@<ACTION_VERSION>
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
      - id: commit
        name: Commit-SHA festhalten
        run: echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"

  mac_validation:
    needs: agent
    runs-on: [self-hosted, macos, apple-validation]
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@<ACTION_VERSION>
        with:
          ref: ${{ needs.agent.outputs.validated_sha }}
      - name: Xcode-Validierung
        run: ./ci/validate-apple-project.sh

Die Action-Version, Authentifizierung und Berechtigungen müssen Sie gegen die aktuelle offizielle Dokumentation prüfen. Platzhalter wie <ACTION_VERSION>, <REPOSITORY>, <SCHEME> und <WORKSPACE_PATH> bleiben absichtlich unaufgelöst. So gelangen keine organisations- oder projektbezogenen Daten in ein kopierbares Beispiel.

Änderungsquellen und Berechtigungsgrenzen

Ein Issue ist nicht dasselbe wie ein externer Pull Request. Die Quelle des Ereignisses bestimmt, welche Daten der Agent lesen darf und ob ein Workflow überhaupt automatisch starten sollte.

Für interne Branches können Sie den Agent-Job mit einem begrenzten Schreibbereich ausführen. Bei externen Pull Requests müssen Sie dagegen mindestens diese Punkte prüfen:

  • Darf der Workflow aus dem Beitrag des Pull Requests stammen oder kann er Workflow-Dateien verändern?
  • Werden Geheimnisse, Token oder Repository-Schreibrechte an nicht vertrauenswürdigen Code weitergegeben?
  • Kann der Agent beliebige Shell-Befehle ausführen, Dateien außerhalb des Arbeitsverzeichnisses lesen oder das Netzwerk nutzen?
  • Wird die Änderung zuerst als Patch geprüft, bevor ein Mac-Runner sie auscheckt?

Kann Claude Code GitHub Actions einen selbst gehosteten Mac-Runner verwenden?
Ja, der Validierungsjob kann auf einen selbst gehosteten Runner geroutet werden, sofern Ihre Workflow-Konfiguration einen passenden Runner auswählt und der Runner für das Repository oder die Organisation zugänglich ist. Das ist keine automatische Sicherheitsfreigabe. Der Runner erhält die Rechte des ausgeführten Jobs und muss deshalb von Agent-Änderung und Produktionssignaturen getrennt werden. GitHub erklärt Labels für selbst gehostete Runner und die Zugriffssteuerung über Runner Groups.

Dürfen externe Pull Requests direkt auf dem Remote-Mac laufen?
Als Standard sollten Sie das nicht erlauben, wenn der Runner Zugang zu Signaturmaterial, produktiven Tokens, privaten Netzwerken oder Restdaten anderer Projekte hat. Ein externer Beitrag kann Buildskripte und Workflow-Dateien ändern. Verwenden Sie stattdessen einen isolierten Validierungsrunner mit nur lesendem Quellzugriff, ohne Veröffentlichungsgeheimnisse und mit einer klaren Abbruchbedingung bei unerwarteten Skriptänderungen.

Die drei wichtigsten Zustände lassen sich so unterscheiden:

Quelle Agent-Rechte Remote-Mac-Zugriff Freigabe
Interner Branch Begrenztes Schreiben auf Branch oder Pull Request Build und Tests ohne Produktionsgeheimnisse Automatisch nach Policy
Externer Pull Request Lesen, Patch oder kontrolliertes Kommentieren Isolierter Runner ohne Schlüsselbund Manuelle Prüfung vor Mac-Job
Geschützter Release-Branch Kein freies Agent-Schreiben Separater Release-Runner Umgebungsgenehmigung und Review

Xcode-Build und feste Commit-Übergabe

Der Mac-Job sollte nicht einfach „den Branch bauen“. Er sollte zuerst den übergebenen Commit-SHA auschecken und danach die Projektstruktur prüfen. Damit wird der Xcode-Schritt zu einer reproduzierbaren Validierung statt zu einem unscharfen End-to-End-Test.

Die Apple-Referenz für Xcode-Kommandozeilentools ist die maßgebliche Quelle für die verwendeten Werkzeuge. Ihre Pipeline sollte mindestens diese Prüfungen ausführen:

  1. Ermitteln, welcher Xcode aktiv ist, statt die installierte Umgebung nur anhand des Runner-Labels anzunehmen.
  2. Prüfen, ob <WORKSPACE_PATH> oder <PROJECT_PATH> tatsächlich vorhanden ist.
  3. Verifizieren, dass <SCHEME> existiert und für die gewünschte Aktion vorgesehen ist.
  4. Abhängigkeiten in einer kontrollierten Umgebung auflösen.
  5. xcodebuild mit festem Derived-Data- und Ergebnisverzeichnis starten.
  6. Exitcode und Ergebnisbundle auswerten.
  7. Strukturierte Logs als Artefakt oder Pull-Request-Kommentar zurückgeben.

Ein Runner, der bei GitHub als „online“ erscheint, beweist weder eine passende Xcode-Version noch einen erfolgreichen Build. Ebenso ist ein leerer Logauszug kein Erfolgssignal. Der Stop-Zustand muss lauten: fehlende Projektdatei, falsches Scheme, fehlende Abhängigkeit, Signaturfehler oder ein nicht erfolgreicher Exitcode beendet die Validierung.

Prüfschritt Beleg Stop-Bedingung
Commit Ausgecheckter SHA im Joblog SHA fehlt oder weicht vom Agent-Output ab
Xcode Ausgabe der aktiven Entwicklungsumgebung Toolchain nicht erwartungsgemäß
Projekt Projekt- oder Workspace-Pfad Datei oder Scheme fehlt
Build xcodebuild-Exitcode und Log Nicht erfolgreicher Exitcode
Ergebnis Ergebnisbundle oder strukturierter Testreport Ergebnis fehlt oder ist nicht lesbar

Wie löst eine Claude-Code-Änderung einen Xcode-Build aus?
Der Agent-Job sollte nach dem Commit den SHA als Job-Output oder Artefakt veröffentlichen. Der Mac-Job wartet mit needs, checkt genau diesen SHA aus und startet ein projektspezifisches Skript. Verwenden Sie kein pauschales „Build latest“, weil dieses Muster bei parallelen Pushes oder nachträglichen Branch-Änderungen die falsche Version prüfen kann.

Szenario: Agent ändert eine Build-Einstellung

Angenommen, Claude Code passt eine Swift-Datei und eine Build-Konfiguration an. Der Agent meldet einen Commit. Der Mac-Job prüft anschließend:

  • ob die Konfigurationsdatei im Commit enthalten ist,
  • ob das erwartete Scheme diese Konfiguration verwendet,
  • ob Abhängigkeiten reproduzierbar aufgelöst werden,
  • ob das Ergebnisbundle tatsächlich aus diesem Lauf stammt.

Schlägt der Build fehl, erhält der Agent nur den strukturierten Fehlerbericht. Er darf nicht eigenständig den Derived-Data-Ordner löschen, Xcode-Projekte umschreiben oder Runner-Konfigurationen verändern. Solche Reparaturen gehören in ein geprüftes Wartungsskript.

Simulator und grafische Testläufe

Reine Kommandozeilen-Builds, Simulator-Tests und grafische UI-Automatisierung haben unterschiedliche Sitzungsanforderungen. Diese Unterschiede müssen im Workflow sichtbar sein.

Ein Kommandozeilen-Build benötigt eine passende Toolchain und einen stabilen Prozess. Ein Simulator-Test benötigt zusätzlich ein verfügbares Simulator-Runtime-Image und ein startbares Gerät. Eine UI-Automatisierung kann eine grafische Sitzung, einen eingeloggten Benutzer und eine bestimmte Fenster- oder Berechtigungsumgebung benötigen. Ob ein Simulatorprozess startet, beweist daher nicht, dass jede UI-Prüfung unbeaufsichtigt funktioniert.

Die Apple-Dokumentation zur Testautomatisierung mit Xcode beschreibt die relevanten Testabläufe. Für jeden grafischen Test sollten Sie die Beobachtbarkeit erhöhen:

  • Protokollieren, ob das erwartete Simulatorgerät gestartet wurde.
  • Speichern, welches Ergebnisbundle erzeugt wurde.
  • Trennen zwischen „Test nicht bestanden“ und „Testprozess nach Sitzungsabbruch verloren“.
  • Nach einem Netzwerk- oder VNC-Abbruch den Prozessstatus prüfen, statt ihn als erfolgreich zu markieren.
  • Keine Aussage über echte Gerätekompatibilität aus einem Simulatorlauf ableiten.
Ausführung Benötigte Umgebung Nachweis
Kommandozeilen-Build Xcode und Projektabhängigkeiten Exitcode, Buildlog
Simulator-Test Xcode, Runtime und gestartetes Gerät Ergebnisbundle, Gerätelog
UI-Automatisierung Zusätzlich geeignete grafische Sitzung Sitzungsstatus, Testreport und Artefakte

Wenn die Sitzung während eines Tests abbricht, gilt der Lauf als unklar oder fehlgeschlagen. Ein automatischer Retry darf nur starten, wenn Sie unterscheiden können, ob ein reproduzierbarer Testfehler oder ein Infrastrukturabbruch vorlag.

Signaturen, Archive und Veröffentlichung

Agent-Code und Signaturmaterial gehören in getrennte Vertrauenszonen. Der Standardfall sollte ein unsignierter Build oder ein Testlauf ohne Zugriff auf Produktionszertifikate, Schlüsselbund, Profile und Veröffentlichungstoken sein.

Wie verhindert die Claude Code Action den Zugriff auf iOS-Signaturzertifikate?
Nicht durch die Action allein. Sie müssen den Zugriff architektonisch entziehen: keine Signaturgeheimnisse im Agent-Job, kein gemeinsamer Schlüsselbund auf dem Validierungsrunner, keine Produktionsprofile im Arbeitsverzeichnis und keine Runner-Gruppe, die interne und externe Beiträge gemeinsam verarbeitet. Die offizielle Sicherheitsdokumentation der Claude Code Action ist dabei eine Prüfgrundlage, ersetzt aber keine eigene Rechte- und Netzwerkplanung.

Für ein benötigtes Archive verwenden Sie einen separaten Release-Job:

  1. Der Agent erstellt nur den geprüften Commit.
  2. Eine geschützte Branch- oder Umgebungspolitik verlangt Review.
  3. Der Release-Runner liegt in einer separaten Runner Group.
  4. Signaturmaterial wird erst nach der Genehmigung verfügbar.
  5. Eingaben wie Team-ID, Profile und Zertifikatpfade sind schreibgeschützt.
  6. Das Archiv wird mit Hash und Buildmetadaten abgelegt.
  7. Veröffentlichung und Signatur werden als eigener, nachvollziehbarer Schritt protokolliert.

Die Apple-Dokumentation zu signiertem Code und Archiven sollten Sie für den konkreten Plattform- und Veröffentlichungsweg heranziehen. Ein externer Pull Request darf niemals direkt auf einen Runner gelangen, der diese Assets hält.

Gemeinsame Runner für mehrere Projekte

Ein geteilter Remote-Mac ist kein neutraler Container. Arbeitsverzeichnisse, Derived Data, Paket-Caches, Simulatorzustände und Benutzerdateien können zwischen Jobs bestehen bleiben. macOS-Runner lassen sich deshalb nicht ohne Weiteres wie kurzlebige Container behandeln.

Planen Sie pro Vertrauensstufe eigene Labels und Runner Groups:

Vertrauensstufe Arbeitsbereich Datenbereinigung Geeigneter Einsatz
Experimentell Eigenes Benutzerkonto und eigener Ordner Nach jedem Lauf prüfen und protokollieren Agent-Änderungen und nicht signierte Tests
Team-intern Projektbezogener Runner oder kontrollierte Gruppe Automatisierte Bereinigung plus Stichprobe Gemeinsame Entwicklungsvalidierung
Veröffentlichung Separater Host und eingeschränkte Gruppe Beweisbare Löschung nach dem Lauf Signatur, Archiv und Release

Die offizielle Übersicht zu selbst gehosteten Runnern und die Betriebsdokumentation für Runner bilden die Grundlage für Registrierung, Labels, Updates und Betrieb. Für Ihre eigene Umgebung müssen Sie zusätzlich festhalten:

  • Herkunft des Jobs und Repository,
  • Commit-SHA,
  • Runner-Name und Benutzerkonto,
  • Arbeitsverzeichnis,
  • verwendete Xcode- und Simulatorumgebung,
  • entfernte Dateien und Cache-Zustand,
  • Ergebnis der Bereinigung.

Welche Wahl gilt bei mehreren Projekten?

  • Wenn die Repositories dieselbe Vertrauensstufe haben und keine geheimen Daten teilen, können Sie einen kontrollierten Team-Runner erwägen.
  • Wenn externe Beiträge, interne Quelltexte oder Signaturdaten zusammentreffen, wählen Sie getrennte Runner Groups.
  • Wenn ein Job Produktionsdaten berührt, verwenden Sie einen unabhängigen Release-Runner.
  • Wenn Sie die Bereinigung nicht beweisen können, gehen Sie auf einen isolierten Host zurück.

Neustart, Wartung und Wiederanlauf

Wie kann ein selbst gehosteter Mac-Runner nach einem Neustart einen Agent-Workflow fortsetzen?
Behandeln Sie einen Neustart nicht als automatische Fortsetzung. Prüfen Sie zuerst, ob der Runner-Prozess wieder registriert ist, ob Netzwerk und Benutzerkonto verfügbar sind und ob der unterbrochene Job bei GitHub als fehlgeschlagen, abgebrochen oder noch aktiv geführt wird. Ein lokaler Prozess darf nicht eigenmächtig einen alten Agent-Schritt erneut ausführen.

Der Wiederanlauf besteht aus einer kontrollierten Kette:

  1. Runner-Status und Verbindung prüfen.
  2. Arbeitsverzeichnis auf unvollständige oder fremde Daten untersuchen.
  3. Alte Prozessreste und gesperrte Simulatoren erfassen.
  4. Einen kleinen, nicht signierenden Prüfjob ausführen.
  5. Einen Commit-SHA erneut validieren, statt einen Branch-Zustand zu übernehmen.
  6. Logs vom Neustart und vom Prüfjob zentral sichern.
  7. Erst danach fehlgeschlagene Jobs gemäß Ihrer Wiederholungsregel neu einreihen.

Die Pipeline sollte externe Logs speichern, damit ein Neustart nicht den einzigen Beleg zerstört. Für den produktiven Betrieb ist ein lokales „online“-Signal zu wenig. Sie brauchen zusätzlich einen erfolgreichen Probejob, korrekte Label-Zuordnung und einen nachvollziehbaren Arbeitsverzeichniszustand.

Führen Sie vor der Freigabe einen vollständigen Test aus: Claude Code bearbeitet eine ungefährliche Änderung, der Agent erstellt den Commit, der Remote-Mac baut und testet genau diesen SHA, der Report wird zurückgegeben, anschließend wird der Host neu gestartet und erneut mit einem kontrollierten Probejob geprüft. Erst wenn jede Übergabe sichtbar ist, entscheiden Sie über den Einsatzgrad:

  • Entwicklung: erlaubt, wenn keine Produktionsgeheimnisse erreichbar sind und Fehler manuell geprüft werden.
  • Team-Nutzung: eingeschränkt freigeben, wenn Runner Groups, Bereinigung und Logs nachweisbar funktionieren.
  • Produktion: erst freigeben, wenn Signatur-Runner, Umgebungsgenehmigung, Wiederanlauf und Rollback separat geprüft sind.

Remote-Mac oder lokaler Kauf

Ein eigener Mac mini kann für dauerhaft hohe Auslastung, lokale Peripherie und physische Geräteverbindungen sinnvoller sein. Ein Kauf bindet jedoch Kapital, verlangt Hardwarebetrieb und erschwert kurzfristige Trennung für externe Beiträge. Ein allgemeiner Linux-Runner ist bei Standardtests flexibel, kann aber Xcode, Simulator und Apple-spezifische Toolchains nicht ersetzen.

Wenn Sie zunächst nur einen isolierten Validierungsrunner für ein Pilotprojekt benötigen, ist ein gemieteter Remote-Mac von MACCOME oft die kontrollierbarere Zwischenlösung: Sie können vollständige Administratorrechte, Neustarttests und die reale Xcode-Kette prüfen, ohne sofort einen eigenen Host zu beschaffen. Informationen zu den verfügbaren Remote-Mac-Optionen von MACCOME können Sie anschließend mit Ihrem erwarteten Nutzungsprofil abgleichen. Für eine langfristige Eigentumslösung bleibt der Kauf eines Mac mini die ehrlichere Option, wenn Sie dauerhaft dieselbe Hardware, lokale Anschlüsse und planbare Dauerlast benötigen.

Die Entscheidung fällt anhand der Betriebsbedingungen:

  • Wählen Sie einen gemieteten Remote-Mac, wenn Sie kurzfristig eine echte macOS-Umgebung, vollständige Verwaltung und einen isolierbaren Testknoten brauchen.
  • Wählen Sie einen eigenen Mac, wenn die Auslastung dauerhaft hoch ist, physische Geräte angeschlossen werden müssen oder Sie den Host langfristig selbst betreiben wollen.
  • Wählen Sie weder Agent- noch Release-Jobs auf demselben Knoten, wenn externe Beiträge und Produktionssignaturen zusammentreffen.
  • Verschieben Sie die Freigabe, wenn Commit-Bindung, Logrückgabe oder Neustarttest noch nicht beweisbar sind.

Für den Start genügt ein nicht signierender Testlauf auf einem separat verwalteten MACCOME-Remote-Mac. Prüfen Sie danach mit Ihrem echten Repository, ob der Agent-Commit, der Xcode-Build, die Simulatorergebnisse, die Bereinigung und der Wiederanlauf tatsächlich zusammenpassen. Erst wenn diese Belege vorliegen, legen Sie Mietdauer und einen möglichen unabhängigen Release-Knoten fest.