fastlane match: Zertifikate synchronisiert, Signierung fehlgeschlagen? Remote-Mac-Fehlerbehebung 2026

Synchronisierung und Signierung sind getrennte Schritte

fastlane match lädt Zertifikate und Provisioning Profile für die verwendete Team- und Match-Konfiguration herunter. Damit ist noch nicht bestätigt, dass der Prozess, der Xcode aufruft, das passende Zertifikat samt privatem Schlüssel verwenden kann oder dass das Projekt das richtige Profil auswählt. Die fastlane-Dokumentation zu neuen Maschinen, Speicherung und readonly beschreibt die Synchronisierung und empfiehlt den Lesemodus für CI.

Halten Sie in der Fehlersuche die einzelnen Bestandteile auseinander:

• Match-Repository und Zugang: Kann der Build-Prozess das Repository erreichen und die benötigten Inhalte entschlüsseln?
• Zertifikat und privater Schlüssel: Liegt eine verwendbare Signierungsidentität für das richtige Team vor?
• Provisioning Profile: Passt das Profil zum Bundle Identifier, zur Zielplattform und zum gewünschten Verwendungszweck?
• Projektkonfiguration: Wählt die konkrete Build-Konfiguration für das betroffene Target die vorgesehene Signieridentität und das passende Profil?
• Ausgabephase: Scheitert der Build, das Archive, der Export der IPA-Datei oder erst der Upload?

Diese Trennung verhindert eine häufige Fehlentscheidung: Ein erfolgreicher Sync ist kein Beweis für eine vollständige Signierungskette. Die Apple-Dokumentation erläutert, dass ein Signierzertifikat und sein privater Schlüssel zusammengehören; fehlt der private Schlüssel oder ist er für den verwendeten Prozess nicht verfügbar, kann das Zertifikat allein die Signierung nicht ermöglichen. Vergleichen Sie dazu Apples Hinweise zu Team-Signierzertifikaten und die technische Beschreibung von Code-Signierzertifikaten.

Erstlauf auf einem neuen Remote Mac

Bei einer Migration ist die wichtigste Frage nicht nur, ob Dateien heruntergeladen wurden, sondern unter welchem Konto und in welchem Projektkontext die eigentliche Signierung stattfindet. Eine manuell gestartete Shell und ein automatisierter Build können mit unterschiedlichen macOS-Benutzern laufen. Auch der verwendete Arbeitsordner, die ausgewählte Lane und die Umgebungsvariablen können voneinander abweichen.

Gehen Sie in dieser Reihenfolge vor:

1. Den tatsächlichen Prozess ermitteln. Lesen Sie im Job-Protokoll nach, welches Konto den fastlane-Aufruf ausführt. Leiten Sie den Kontonamen nicht aus einer interaktiven Remote-Desktop-Sitzung ab.
2. Den Projektkontext festhalten. Notieren Sie Arbeitsverzeichnis, Projektdatei oder Workspace, Scheme, Target und die Build-Konfiguration, die den fehlgeschlagenen Lauf ausgelöst haben.
3. Den verwendeten Match-Aufruf prüfen. Bestätigen Sie Team und Verwendungszweck der synchronisierten Assets. Vergleichen Sie den Aufruf mit der vorgesehenen Lane, statt eine andere Match-Konfiguration testweise einzusetzen.
4. Den Zugang getrennt prüfen. Verifizieren Sie, dass der Prozess das Repository erreicht und die nötigen Zugangsdaten auf sichere Weise erhält. Geben Sie Geheimnisse weder auf der Befehlszeile aus noch in ein dauerhaftes Job-Protokoll.
5. Erst danach die Signierung untersuchen. Wenn der Sync erfolgreich war, aber Xcode keine Identität findet, prüfen Sie Schlüsselbund und privaten Schlüssel, bevor Sie erneut synchronisieren oder Zertifikate austauschen.

Für eine CI-Prüfung kann ein vorhandener Veröffentlichungsaufruf beispielsweise den dokumentierten readonly-Modus verwenden:

bundle exec fastlane match appstore --readonly

Das ist ein Beispiel für den Aufruf von match, kein vollständiger Build-Befehl. Ersetzen Sie keine Team-, Repository- oder Zugangswerte durch echte Geheimnisse in einer gemeinsam sichtbaren Ausgabe. Ein redigiertes Prüfprotokoll kann die relevanten Zustände festhalten, ohne private Daten preiszugeben:

Ausführungskonto: [redigiert]
Arbeitsverzeichnis: [Projektpfad]
Match-Zugriff: erfolgreich / fehlgeschlagen
Entschlüsselung: erfolgreich / fehlgeschlagen
Signierungsidentität im Build-Kontext: vorhanden / nicht vorhanden
Fehlerphase: Build / Archive / IPA-Export / Upload

Diese Zeilen sind ein eigenes Prüfschema und keine behauptete fastlane-Standardausgabe. Sie helfen, einen Repository-Fehler von einem Schlüsselbund- oder Xcode-Fehler zu unterscheiden. Wenn der Remote Mac als wiederkehrende Build-Umgebung dient, sollte dieselbe dokumentierte Prozessbeschreibung auch für die Auswahl einer Mac-Umgebung nachvollziehbar sein.

Vorhandenes Zertifikat, aber kein verwendbarer privater Schlüssel

Ein Zertifikat kann sichtbar oder synchronisiert sein, während der private Schlüssel dem aktuellen macOS-Benutzer nicht zugänglich ist. In diesem Fall behebt ein erneuter Download des Zertifikats nicht zwingend die Ursache. Prüfen Sie daher zuerst, ob die erwartete Signierungsidentität im Kontext des tatsächlichen Build-Prozesses verfügbar ist.

Öffnen Sie die Schlüsselbundverwaltung mit dem Konto, unter dem der Build läuft, und prüfen Sie die entsprechende Identität. Entscheidend ist nicht allein, ob ein Zertifikat angezeigt wird, sondern ob es mit dem zugehörigen privaten Schlüssel verbunden und für den Signiervorgang erreichbar ist. Die Apple-Dokumentation zu Code Signing ordnet die Signierung in die Integritätsprüfung der App ein; Apples Erklärung zu Code-Signatur-Zertifikaten beschreibt die Rolle der Schlüsselkomponenten.

Wenn eine lokale Sitzung signieren kann, der Remote-Prozess aber nicht, vergleichen Sie die beiden Kontexte: Benutzerkonto, verfügbare Schlüsselbünde und verwendete Identität. Ein erfolgreicher lokaler Build belegt nicht, dass ein automatisierter Prozess auf dieselben Schlüssel zugreifen kann. Widerruf oder Neuerstellung sollte erst nach Prüfung der Team-Konfiguration und der Folgen für andere Builds erwogen werden.

Provisioning Profile stimmt nicht mit dem Target überein

Ein erfolgreich installiertes iOS Provisioning Profile belegt nicht, dass Xcode es für jedes Target oder jede Konfiguration automatisch auswählt. Ein Projekt kann unterschiedliche Bundle Identifier für App, Erweiterung oder weitere Targets verwenden. Ebenso können Entwicklungs- und Veröffentlichungsabläufe verschiedene Signiereinstellungen benötigen.

Prüfen Sie im betroffenen Build-Kontext:

• Welches Target und welcher Bundle Identifier tatsächlich archiviert werden.
• Ob das installierte Profil für diesen Bezeichner und den vorgesehenen Verwendungszweck erstellt wurde.
• Welche Code-Signatureinstellungen für Scheme und Build-Konfiguration aktiv sind.
• Ob automatische oder manuelle Signierung verwendet wird und ob diese Wahl zur erwarteten Profilzuordnung passt.

Apple beschreibt den Zusammenhang zwischen Signiereinstellungen und Build-Konfiguration in der Xcode-Referenz zu Build Settings. Die Apple-Seite zum Erstellen eines App-Store-Provisioning-Profils hilft, den vorgesehenen Profilzweck zuzuordnen. Verwenden Sie diese Angaben als Abgleich, nicht als Anlass, für jedes Target vorsorglich neue Profile anzulegen.

Ein Profil kann also vorhanden sein und trotzdem für den konkreten Archive-Aufruf ungeeignet sein. Ermitteln Sie zuerst, welches Profil Xcode tatsächlich für das jeweilige Target heranzieht. Ein Wechsel des Bundle Identifier oder der Signiermethode, der nur in einer Konfiguration vorgenommen wurde, kann einen Unterschied zwischen lokalem Debug-Build und Remote-Veröffentlichungsbuild erklären.

Lokaler Erfolg, Remote-Fehler und readonly CI

Wenn das Projekt lokal signiert, aber auf dem Remote Mac scheitert, trennen Sie den Fehler entlang der Zugriffsgrenzen. Ein fehlgeschlagener Repository-Zugriff ist etwas anderes als eine fehlgeschlagene Entschlüsselung; beides ist wiederum nicht dasselbe wie eine fehlende Signierungsidentität in Xcode.

readonly eignet sich für einen CI-Lauf, der vorhandene Zertifikate und Profile nutzen soll, ohne die Signierungsdateien zu verwalten oder zu erneuern. Der Modus ist keine Reparaturfunktion: Er erzeugt keinen fehlenden privaten Schlüssel, passt ein falsches Provisioning Profile nicht an das Target an und korrigiert keine Xcode-Build-Einstellung. Die Empfehlung für readonly in CI ist in der Dokumentation von fastlane match beschrieben.

Führen Sie deshalb eine kontrollierte Prüfung aus, ohne den Veröffentlichungsablauf mit zusätzlichen Schreibaktionen zu verändern. Ist der Match-Zugriff erfolgreich, aber die Signierungsidentität fehlt, untersuchen Sie den Schlüsselbund. Sind Identität und Schlüssel verfügbar, die Signierung scheitert jedoch weiterhin, vergleichen Sie Profil und Projektkonfiguration. Erst wenn diese Stufen passen, werten Sie die konkrete Fehlermeldung der nächsten Build-Phase aus.

Archive-Fehler nicht mit IPA-Export oder Upload verwechseln

Ein gewöhnlicher Entwicklungsbuild, ein Archive, der Export einer IPA-Datei und deren Upload sind getrennte Stationen. Ein Debug-Ergebnis bestätigt daher nicht automatisch, dass die gewählte Distributionsidentität und das Profil für das Veröffentlichungs-Archive passen. Ebenso beweist ein erfolgreich erzeugtes Archive noch nicht, dass Export oder Upload abgeschlossen wurden.

Lesen Sie die Fehlermeldung zusammen mit dem letzten erfolgreich abgeschlossenen Schritt. Scheitert schon die Signierung beim Archive, prüfen Sie Identität, privaten Schlüssel, Profil und die für das Target aktive Konfiguration. Wird das Archive erstellt, aber der IPA-Export schlägt fehl, untersuchen Sie die Exportauswahl und den vorgesehenen Verwendungszweck. Liegt bereits eine IPA-Datei vor, gehört ein anschließender Upload-Fehler nicht mehr zur Synchronisierung der Zertifikate.

Apple trennt die Abläufe in seiner Anleitung zur Verteilung einer App aus Xcode. Ziehen Sie daraus keine pauschale Ursache für eine einzelne Fehlermeldung: Ordnen Sie den Fehler dem tatsächlich fehlgeschlagenen Schritt zu und vergleichen Sie die passende Konfiguration. Für die Abgrenzung von Exportproblemen gibt es außerdem einen eigenen Beitrag zur Fehlersuche bei fastlane gym und dem IPA-Export.

FAQ zu Remote-Signierung und Match

Match ist erfolgreich, Xcode findet die Identität aber nicht

Prüfen Sie, ob der Build unter demselben macOS-Konto läuft, in dessen Kontext die Signierungsidentität verfügbar ist. Die Synchronisierung kann erfolgreich sein, während der private Schlüssel für diesen Prozess unerreichbar bleibt. Unterscheiden Sie außerdem zwischen einem Repository- oder Entschlüsselungsfehler und einer tatsächlich fehlenden Identität im Signiervorgang.

Privater Schlüssel liegt nicht im Anmelde-Schlüsselbund

Ermitteln Sie zunächst den Schlüsselbund, auf den der automatisierte Prozess zugreift, und prüfen Sie die Identität in genau diesem Kontext. Ein anderer Schlüsselbund oder eine andere Benutzersitzung kann erklären, warum ein manueller Test anders ausfällt als der Job. Importieren Sie keine privaten Schlüssel aus einem unbekannten Ablageort und protokollieren Sie keine Geheimnisse.

readonly für einen Veröffentlichungsbuild

Ein CI-Veröffentlichungsbuild kann vorhandene Match-Dateien im readonly-Modus verwenden. Das ist sinnvoll, wenn die Signierungsassets zentral verwaltet werden und der Build sie lediglich lesen soll. readonly gleicht jedoch weder ein falsch zugeordnetes Profil aus noch behebt es fehlende Schlüssel oder fehlerhafte Xcode-Einstellungen; diese Prüfungen bleiben Teil der Abnahme.

Lokal erfolgreich, Remote-Archive fehlgeschlagen

Beginnen Sie mit dem Remote-Ausführungskonto und der Konfiguration des Archive-Schritts. Prüfen Sie anschließend die verfügbare Signierungsidentität samt privatem Schlüssel und die Zuordnung des Provisioning Profiles zum betroffenen Target. Erst danach entscheiden Sie, ob der Fehler beim Archive, beim Export der IPA-Datei oder beim späteren Upload entsteht.

Entscheidung nach Fehlerbild und Abnahmeprotokoll

Die folgende Gegenüberstellung hilft, die nächste Prüfung anhand des beobachteten Zustands auszuwählen. Sie ersetzt keine Diagnose anhand des konkreten Job-Protokolls.

Für eine belastbare Abnahme verwenden Sie das Zielprojekt und den vorgesehenen Veröffentlichungsablauf, statt nur einen vereinfachten lokalen Build zu wiederholen. Prüfen Sie das erzeugte Archive und die Signierungsinformationen im Zusammenhang mit der ausgewählten Verteilung. Apple beschreibt, wie Xcode Apps archiviert und für die Verteilung vorbereitet, in der Dokumentation zur Xcode-App-Verteilung.

Dokumentieren Sie bei der Abnahme außerdem, woher die Zugangsdaten stammen und welche Ergebnisse gefahrlos weitergegeben werden dürfen. Veröffentlichen Sie weder private Schlüssel noch Entschlüsselungsdaten, Zugangstoken oder vollständige vertrauliche Umgebungsvariablen. Das ist nicht nur eine Frage der Fehlersuche: Bei CI-Zugängen und Signierungsassets müssen Datenschutz und Zugriffsschutz im Sinne der DSGVO mitgedacht werden.

Die Prüfung bestätigt ausschließlich den konkret ausgeführten Ablauf. Sie beweist weder, dass andere Apps dieselbe Profilzuordnung verwenden, noch dass eine andere Distributionsart ebenfalls funktioniert. Wiederholen Sie die Abnahme nach Änderungen am Target, an der Signierkonfiguration oder am verwendeten Veröffentlichungsweg.

Wenn der Fehler im Ausführungskontext und nicht in der Signierkonfiguration liegt, ist eine kontrollierbare Remote-Mac-Umgebung eine mögliche Alternative zu einem zusätzlichen lokalen Build-Rechner. Lokale Macs binden Kapital und müssen für CI-Aufgaben verfügbar bleiben; allgemeine CI-Umgebungen bieten nicht immer denselben direkten Zugriff auf die benötigte macOS- und Xcode-Umgebung; selbstverwaltete Rechner verursachen zudem laufende Pflege für Zugangsschutz, Updates und Wiederherstellung. Für zeitlich begrenzte Veröffentlichungs- oder Migrationsaufgaben kann die Miete eines Remote Mac über NodeMini daher sinnvoll sein, sofern die nötigen Werkzeuge und Zugriffswege vorab geprüft werden. Für dauerhaft ausgelastete Builds oder notwendige physische Gerätezugriffe sollten Sie dagegen einen dauerhaft verfügbaren Rechner beziehungsweise eine passende Geräteumgebung bevorzugen.