Prüfen Sie zuerst das tatsächliche macOS-Konto des Runners und den Schlüsselbund, den dieses Konto im Workflow verwendet; danach kontrollieren Sie Signaturidentität und passendes Bereitstellungsprofil. Eine erfolgreiche SSH-Anmeldung oder lokale Xcode-Signierung belegt nicht, dass der Runner im eigenen Ausführungskontext signieren kann.
Für iOS- und macOS-Entwickler: Wenn ein lokaler Build gelingt, die Archivierung oder Signierung in GitHub Actions aber fehlschlägt, grenzen Sie die Ursache anhand der Job-Protokolle ein.
Für DevOps-Verantwortliche: Machen Sie Runner-Konto, Dienststatus und Schlüsselbundzugriff im tatsächlichen Workflow nachvollziehbar.
Für Release- und Credential-Verantwortliche: Trennen Sie Zertifikat, privaten Schlüssel, Schlüsselbund und Profil, bevor Sie Signiermaterial ändern.
[ SECTION_01 ] GitHub Actions: Xcode-Signierung fehlgeschlagen – zuerst die Fehlergrenze bestimmen
„Signierung fehlgeschlagen“ bezeichnet nicht automatisch einen defekten oder abgelaufenen Berechtigungsnachweis. Der Fehler kann bereits beim Build, bei der Archivierung, bei der Auswahl einer Identität oder erst beim eigentlichen Signieren auftreten. Der erste Auftrag besteht deshalb darin, den fehlgeschlagenen Schritt und den dafür verantwortlichen Kontext zu sichern.
Vergleichen Sie zunächst den Commit, das Scheme, das Ziel und die relevanten Build-Einstellungen des CI-Laufs mit dem lokalen Lauf. Wenn unterschiedliche Commits oder Build-Ziele verwendet werden, sind die Ergebnisse nicht direkt vergleichbar. Notieren Sie außerdem die Runner-Kennung und den Benutzernamen, unter dem der fehlgeschlagene Job tatsächlich ausgeführt wurde. GitHub beschreibt die Protokoll- und Dienstprüfung für selbst gehostete Runner in der Dokumentation zur Fehlerbehebung bei selbst gehosteten Runnern.
Legen Sie dann eine kurze Beweiskette an: fehlgeschlagener Workflow-Schritt, relevante Xcode-Ausgabe, verwendetes Scheme und Target sowie Ergebnis eines vergleichbaren lokalen Builds. Ein allgemeiner Jobstatus wie „fehlgeschlagen“ reicht nicht, um Projektfehler von Problemen des Mac-Knotens zu unterscheiden.
| Beobachtung im Build | Zuständigkeit für die erste Prüfung | Bewertung und nächster Schritt |
|---|---|---|
| Build schlägt vor Archivierung oder Signierung fehl | Projektverantwortliche | Hoch: Scheme, Target und Build-Einstellungen gegen den Commit prüfen |
| Archivierung gelingt, aber es wird keine erwartete Identität ausgewählt | Xcode- und Release-Verantwortliche | Hoch: Signiermodus, Team-Zuordnung und Auswahlparameter untersuchen |
| Identität ist im Job nicht sichtbar oder nicht verwendbar | CI- und Runner-Verantwortliche | Hoch: Job-Konto und Schlüsselbundzugriff feststellen |
| Identität ist verfügbar, die Signierung scheitert dennoch | Signierungsadministration | Mittel bis hoch: privaten Schlüssel und Profilzuordnung prüfen |
| Änderungen an Zugriff oder Credentials wurden bereits vorgenommen | Sicherheitsverantwortliche | Hoch: Umfang, Freigabe und Rückrollweg dokumentieren |
Die Bewertungen sind eine redaktionelle Reihenfolge für die Diagnose, keine Messwerte und keine Aussage über die Häufigkeit eines Fehlers. Sie helfen, zuerst die Prüfungen auszuführen, die eine klare Verantwortung und ein beobachtbares Ergebnis liefern.
[ SECTION_02 ] Projektverantwortliche gleichen Scheme, Target und Signiermodus ab
Wer das iOS- oder macOS-Projekt betreut, sollte zunächst feststellen, ob der Workflow denselben Signierpfad wie die erwartete Freigabe verwendet. Automatische und manuelle Signierung sind unterschiedliche Projektentscheidungen. Ein Workflow kann daher trotz vorhandener Credentials scheitern, wenn Build-Parameter oder Projekteinstellungen nicht zum gewählten Weg passen.
Gehen Sie die Projektkonfiguration in dieser Reihenfolge durch:
- Prüfen Sie, welches Scheme der fehlgeschlagene Job tatsächlich verwendet. Halten Sie den Namen aus dem Workflow fest und gleichen Sie ihn mit dem lokalen Freigabevorgang ab.
- Prüfen Sie das betroffene Target und den Build-Konfigurationstyp. Ein erfolgreiches Haupt-App-Target beweist nicht, dass Erweiterungen oder weitere Targets gleich konfiguriert sind.
- Vergleichen Sie die Build-Parameter des Workflows mit den Einstellungen des Projekts. Die Xcode-Referenz zu Build-Einstellungen beschreibt die dafür relevanten Xcode-Einstellungen; verwenden Sie sie, um konkrete Abweichungen zu überprüfen, statt Werte zu erraten.
- Halten Sie fest, ob der Workflow automatische oder manuelle Signierung erwartet. Ändern Sie nicht beide Wege gleichzeitig, weil das die Ursache einer Verbesserung oder Verschlechterung unklar macht.
- Gleichen Sie Bundle Identifier und Team-Zuordnung des betroffenen Targets mit der beabsichtigten App ab.
Für die Übergabe an die CI-Verantwortlichen braucht es anschließend eine klare Aussage: „Das Projekt fordert Identität X für Target Y an“ oder „Die Auswahl erfolgt automatisch und muss im Build-Protokoll nachgewiesen werden.“ Verwenden Sie für Konto, Team-ID, Bundle Identifier und Identitätsnamen ausschließlich interne Platzhalter in gemeinsam genutzten Diagnoseunterlagen. Signiermaterial oder Geheimnisse gehören nicht in einen Fehlerbericht.
Xcode führt beim Bauen und Ausführen eines Projekts mehrere Schritte aus. Deshalb sollte das Team den konkreten Build- oder Archivierungsschritt im Protokoll mit dem beabsichtigten Ziel abgleichen, statt aus einer späteren Fehlermeldung auf den gesamten Ablauf zu schließen. Die Apple-Dokumentation zum Bauen und Ausführen einer App bietet den offiziellen Bezugspunkt für diese Abgrenzung.
[ SECTION_03 ] CI-Verantwortliche prüfen Konto und macOS-Schlüsselbund im Job-Kontext
Der SSH-Benutzer, das Konto einer geöffneten Desktop-Sitzung und das Konto des Runner-Prozesses können auseinanderfallen. Für die Diagnose zählt, was der fehlgeschlagene Workflow tatsächlich verwendet. Eine Prüfung in einem separaten Terminal ist nützlich als Vergleich, aber kein Ersatz für eine Prüfung innerhalb des Jobs.
Führen Sie für die Untersuchung einen vorübergehenden Diagnose-Schritt im betroffenen Workflow aus. Erfassen Sie darin die Benutzerkennung, die Runner-Kennung und eine kontrollierte Abfrage des Schlüsselbundkontexts. Geben Sie weder Kennwörter noch private Schlüssel oder den Inhalt von Credentials aus. Dokumentieren Sie stattdessen, ob der erwartete Schlüsselbund erreichbar ist und ob die Signaturidentität im selben Job-Kontext auftaucht.
Vergleichen Sie anschließend drei getrennte Beobachtungen:
- Workflow: Welcher Benutzer führt den fehlgeschlagenen Job aus, und welcher Schlüsselbund ist in diesem Kontext verfügbar?
- SSH-Sitzung: Unter welchem Konto gelingt der manuelle Test, und welche Schlüsselbundumgebung ist dort aktiv?
- Runner-Dienst: Welcher Status und welche Protokolle gehören zur Runner-Instanz, die den Job angenommen hat?
Wenn der Runner durch launchd als Dienst verwaltet wird, werten Sie Dienststatus und Runner-Protokolle gemeinsam mit der Ausgabe des Workflow-Schritts aus. GitHub stellt eine Anleitung zur Konfiguration des selbst gehosteten Runner-Dienstes bereit. Sie sollte herangezogen werden, um die tatsächliche Dienstverwaltung zu prüfen; eine erfolgreich gestartete SSH-Shell belegt den Dienstkontext nicht.
Eine Identität in einer interaktiven Sitzung ist noch kein Nachweis für einen erfolgreichen CI-Signiervorgang. Erst wenn die Prüfung im Job dieselbe Identität und den erforderlichen Zugriff belegt, ist die Schlüsselbundseite der Diagnose ausreichend eingegrenzt.
Übergibt die CI-Verantwortung die Ergebnisse an das Signierungsteam, sollten Konto, Runner-Kennung und Schlüsselbundbefund zusammen mit dem betreffenden Job-Protokoll genannt werden. Damit kann die nächste Rolle prüfen, ob eine Identität fehlt oder zwar vorhanden, aber nicht für diesen Prozess nutzbar ist.
[ SECTION_04 ] Signierungsadministration unterscheidet Identität, privaten Schlüssel und Profil
Eine angezeigte Zertifikatsidentität beweist für sich allein nicht, dass der ausführende Prozess den dazugehörigen privaten Schlüssel verwenden kann. Apple erläutert Identitäten und deren Verwendung in der Dokumentation zu Code-Signaturidentitäten sowie in der Technote zu Code-Signaturzertifikaten. Prüfen Sie diese Komponenten getrennt, bevor Sie ein Zertifikat neu importieren oder ersetzen.
Für die Diagnose sollte die Signierungsadministration diese Nachweise zusammentragen:
- Identität: Wird die erwartete Signaturidentität im Kontext des Workflow-Jobs gefunden?
- Privater Schlüssel: Ist der zugehörige Schlüssel im selben Ausführungskontext nutzbar, oder wurde lediglich ein Zertifikat ohne passenden Schlüssel bereitgestellt?
- Schlüsselbund: Kann der Runner-Prozess auf den relevanten Schlüsselbund zugreifen, und entspricht dessen Zustand der beabsichtigten CI-Konfiguration?
- Bereitstellungsprofil: Stimmen App-ID, Team-Zuordnung und vorgesehener Verwendungszweck mit dem konkreten Target überein?
Für die Profilseite beschreibt Apple, wie ein App-Store-Bereitstellungsprofil erstellt wird. Nutzen Sie diese Dokumentation, um die Profilzuordnung und den vorgesehenen Zweck zu kontrollieren. Ein unpassendes Profil sollte nicht vorschnell als Schlüsselbundproblem behandelt werden. Umgekehrt löst ein passendes Profil keinen fehlenden oder unzugänglichen privaten Schlüssel.
Vor einem Austausch oder erneuten Import halten Sie fest, welche Signiermaterialien betroffen sind, wer die Änderung freigegeben hat und wie der vorherige Zustand wiederhergestellt werden kann. Eine ungezielte Importserie erzeugt zusätzliche Zustände und erschwert den Vergleich mit dem ursprünglichen Fehler. Änderungen sollten jeweils einzeln erfolgen und mit einem erneuten Lauf desselben Build-Ziels geprüft werden.
[ SECTION_05 ] Häufige Ursachen im FAQ
Lokale Signierung gelingt, im Workflow fehlt die Identität
Der lokale Xcode-Lauf kann unter einem anderen Konto und in einer anderen Sitzung stattfinden als der Job. Vergleichen Sie die Ausgabe aus dem Workflow mit der lokalen Prüfung: Benutzer, Schlüsselbundkontext, angeforderte Identität und Build-Ziel. Wenn die Identität nur lokal sichtbar ist, liegt der nächste Prüfschritt beim Runner-Kontext. Wenn sie im Job vorhanden ist, gehen Sie zur Prüfung des privaten Schlüssels und des Profils über.
SSH kann signieren, der Runner meldet aber einen Signierungsfehler
Der SSH-Test beantwortet, ob die angemeldete Sitzung signieren kann. Er beantwortet nicht, ob der Runner-Dienst denselben Benutzer und denselben Schlüsselbund nutzt. Führen Sie die Benutzer- und Schlüsselbundprüfung im fehlgeschlagenen Job aus. Erst der Vergleich dieser Ausgabe mit SSH und dem Runner-Dienst zeigt, ob die Sitzungen voneinander abweichen oder ob die Ursache später im Signierpfad liegt.
Runner-Konto und verwendeter Schlüsselbund bleiben unklar
Legen Sie einen Diagnose-Schritt im betroffenen Job an und erfassen Sie darin die Benutzerkennung sowie den Schlüsselbundbefund, ohne geheime Inhalte auszugeben. Ordnen Sie die Ausgabe der Runner-Kennung und dem zugehörigen Job-Protokoll zu. Bei einem als Dienst betriebenen Runner ergänzen Sie die Dienstprüfung. Eine Prüfung über SSH oder in der grafischen Sitzung ist nur ein Vergleichswert, kein Beleg für den Workflow.
Identität vorhanden, Signierung trotzdem nicht erfolgreich
Gehen Sie nicht direkt davon aus, dass das Zertifikat ersetzt werden muss. Prüfen Sie zuerst, ob der Runner den privaten Schlüssel zur Identität verwenden kann. Ist das belegt, kontrollieren Sie anschließend die Zuordnung des Bereitstellungsprofils zum Target, zur App-ID und zum vorgesehenen Zweck. Trennen Sie diese Befunde, damit die zuständige Rolle genau die fehlerhafte Komponente ändern kann.
[ SECTION_06 ] Release-Verantwortliche nehmen eine Reparatur mit dem echten Artefakt ab
Ein grüner Runner-Status und ein erfolgreicher Build sind kein Nachweis, dass das Release-Artefakt korrekt signiert wurde. Die Abnahme muss den vorgesehenen Veröffentlichungsweg prüfen. Verwenden Sie dafür einen sauberen Workflow-Lauf mit dem echten Release-Ziel und sichern Sie die zugehörigen Protokolle sowie das erzeugte Archiv.
Prüfen Sie das Ergebnis in einer nachvollziehbaren Reihenfolge:
- Bestätigen Sie, dass der Workflow den vorgesehenen Commit, das Scheme und das Release-Target verwendet.
- Kontrollieren Sie im Protokoll, welcher Signierpfad und welche Identität für das konkrete Target gewählt wurden.
- Verifizieren Sie die Signierung des erzeugten Archivs mit den dafür vorgesehenen Apple-Werkzeugen und halten Sie das Ergebnis fest. Die Apple-Dokumentation zu Identitäten und Signaturzertifikaten ist dabei die Referenz, nicht allein die Meldung „Build erfolgreich“.
- Vergleichen Sie das Ergebnis mit dem erwarteten Bereitstellungsprofil und der beabsichtigten App-ID.
- Führen Sie nach jeder relevanten Änderung denselben Prüfweg erneut aus und dokumentieren Sie, was sich geändert hat.
Wenn Konto oder Schlüsselbundzugriff zwischen Läufen nicht reproduzierbar sind, behandeln Sie das nicht als erledigten Fehler. Isolieren Sie den Signierjob zunächst oder prüfen Sie, ob ein eigener Mac-Knoten mit klarer Zuständigkeit erforderlich ist. Eine Produktionsfreigabe sollte warten, bis die Beweiskette vom Workflow-Kontext bis zum signierten Archiv nachvollziehbar ist.
[ SECTION_07 ] Freigabe-Checkliste für die Übergabe
Verwenden Sie die folgende Liste vor der Freigabe. Jeder Punkt sollte durch eine konkrete Protokollausgabe, Projekteinstellung oder dokumentierte Freigabe belegbar sein.
- [ ] Commit, Scheme und betroffenes Target des lokalen Vergleichs stimmen mit dem Workflow überein.
- [ ] Der konkrete fehlgeschlagene Schritt ist als Build, Archivierung, Identitätsauswahl oder Signierung eingeordnet.
- [ ] Das tatsächliche macOS-Konto wurde innerhalb des betroffenen Jobs geprüft.
- [ ] Runner-Kennung und Runner-Dienstprotokolle gehören zu derselben Job-Ausführung.
- [ ] Schlüsselbundzugriff wurde im Workflow-Kontext geprüft und nicht nur über SSH abgeleitet.
- [ ] Erwartete Signaturidentität und Verfügbarkeit des privaten Schlüssels wurden getrennt bewertet.
- [ ] Bundle Identifier, Team-Zuordnung und Bereitstellungsprofil passen zum Release-Target.
- [ ] Änderungen an Credentials oder Berechtigungen sind freigegeben, begrenzt und rückrollbar.
- [ ] Ein sauberer Lauf erzeugt das erwartete signierte Archiv; Protokoll und Prüfergebnis sind gesichert.
Die Sicherheitsprüfung gehört in denselben Freigabeprozess. Bestimmen Sie, welche Repositories und Workflow-Auslöser Zugriff auf Signiermaterial erhalten. GitHub beschreibt Risiken und Schutzmaßnahmen in der Dokumentation zur sicheren Verwendung von GitHub Actions. Verwenden Sie sie, um die Berechtigungsgrenzen zu prüfen, statt einen Signierungsfehler durch pauschale Rechteausweitung zu überdecken.
Insbesondere bei gemeinsam genutzten Runnern müssen Aufgabenrouting und Zugriff auf Credentials zusammen betrachtet werden. Ein Job, der nicht vertrauenswürdige Änderungen verarbeitet, sollte nicht automatisch denselben Zugang zu Produktionssigniermaterial erhalten wie ein kontrollierter Release-Job. Halten Sie fest, wer eine Berechtigungsänderung autorisiert hat, für welche Workflows sie gilt und wie sie zurückgenommen wird. Lassen sich diese Grenzen nicht zuverlässig festlegen, sollte der Signierjob bis zur Klärung isoliert bleiben.
[ SECTION_08 ] Wann ein anderer Mac-Ausführungskontext sinnvoll ist
Wenn die Fehlerursache nicht im Projekt, sondern in einem wechselnden oder schwer überprüfbaren Runner-Kontext liegt, lohnt sich ein Vergleich der Betriebsmodelle. Ein bestehender, gemeinsam genutzter Knoten kann zusätzliche Abstimmung bei Konten, Schlüsselbundzugriff und Workflow-Berechtigungen erfordern. Ein eigens verwalteter Mac-Ausführungskontext kann die Zuständigkeit klarer machen, verlangt aber weiterhin eine saubere Credential-Verwaltung und Abnahme.
Wer dauerhaft verfügbare macOS-Ausführung benötigt, kann die Zugangsmöglichkeiten zu einem Remote-Mac auf der NOVAKVM-Übersichtsseite prüfen. Das ist besonders dann eine Option, wenn ein CI-Team eine Mac-Umgebung für kontrollierte Builds benötigt, ohne die Hardware selbst zu beschaffen und zu betreiben. Für Teams, die stattdessen Eigentum und eigenen Betrieb bevorzugen, ist auch die Entscheidung für einen Mac mini M4 zur eigenen Nutzung eine andere, nachvollziehbare Betriebsvariante.
Die Wahl hängt vom Betrieb ab: Ein eigener Mac passt eher, wenn die Umgebung langfristig stabil ausgelastet sein muss oder lokale physische Anschlüsse benötigt werden. Ein Linux-Runner kann Aufgaben ohne macOS-Abhängigkeit weiterhin übernehmen, ersetzt aber keine Xcode-Signierung auf einem Mac. Wenn vor allem ein kontrollierbarer, zeitlich begrenzter oder extern erreichbarer macOS-Knoten fehlt, kann die Remote-Mac-Option von NOVAKVM den Vergleich wert sein. Entscheidend ist nicht, wo der Mac steht, sondern ob Konto, Schlüsselbund, Signieridentität und Release-Artefakt im tatsächlichen Workflow überprüfbar bleiben.