Ein Provisioning Profile verbindet laut Apple-Dokumentation zur Struktur von Provisioning Profiles unter anderem App-ID, Team, Entitlements und Zertifikate. Genau deshalb sollten Sie bei einem fastlane match-Signaturfehler nicht sofort match nuke ausführen oder Zertifikate neu erstellen: Prüfen Sie zuerst in dieser Reihenfolge das Signatur-Repository und die Entschlüsselung, die vollständige Signaturidentität in der Keychain, die Profile-Zuordnung, die Entitlements und anschließend die CI-Konfiguration. Erst wenn ein Asset nachweislich abgelaufen oder nicht wiederherstellbar ist, beginnen Sie eine kontrollierte Rotation.

Diese Checkliste richtet sich an Sie, wenn Sie fastlane match auf einem Remote Mac ausführen und ein Archive plötzlich keine Signaturidentität findet. Sie passt ebenso zu kleinen Teams, deren lokale Builds funktionieren, deren unbeaufsichtigte CI-Aufgabe aber scheitert, sowie zu Entwicklern, die eine manuelle Zertifikatsverwaltung in eine zentrale Signaturverwaltung überführen.

Die erste Diagnose: vier Fehlerlagen statt eines pauschalen Zertifikatsproblems

Beginnen Sie mit einem kleinen, anonymisierten Log-Ausschnitt. Entfernen Sie Repository-Adressen, Branch-Namen, Team-IDs, Bundle IDs, Token, Dateipfade, Keychain-Namen und alle Inhalte von Umgebungsvariablen. Bewahren Sie zusätzlich den Exit-Status des fehlgeschlagenen Befehls, die aktive Xcode-Auswahl, Scheme, Configuration, Export-Ziel und die relevanten Build Settings auf.

Die entscheidende Frage lautet nicht „Warum findet Xcode kein Zertifikat?“, sondern: An welcher Schicht ist die Kette gebrochen?

  • Asset-Beschaffung: match erreicht das Repository oder den Objektspeicher nicht, kann den gewünschten Branch nicht lesen oder kann die verschlüsselten Assets nicht entschlüsseln.
  • Installation: Zertifikat und private Schlüssel wurden nicht als nutzbare Signaturidentität in die erwartete Keychain importiert.
  • Zuordnung: Das richtige Profile ist vorhanden, wird aber dem falschen Target, Bundle ID, Team oder Zertifikat zugeordnet.
  • Verifikation: Die Signierung läuft scheinbar durch, scheitert jedoch beim Entitlement-Abgleich, beim Export oder bei der abschließenden Validierung.

Die offizielle fastlane-Fehlerdiagnose behandelt diese Ebenen getrennt. Übernehmen Sie diese Trennung auch in Ihrem Log. Ein Eintrag wie No signing certificate beweist allein nicht, dass das Zertifikat widerrufen werden muss.

Als erste Diagnosepunkte genügen vier kurze Prüfungen:

  1. Erreicht der CI-Prozess das Signatur-Repository mit eigenen Zugangsdaten?
  2. Existiert in der erwarteten Keychain eine vollständige Signaturidentität mit privatem Schlüssel?
  3. Passt das installierte Provisioning Profile zum betroffenen Target?
  4. Läuft ein minimales Archive mit demselben Commit und derselben Export-Konfiguration?

Diese Reihenfolge spart Zeit, weil sie einen fehlgeschlagenen Download nicht mit einem Keychain-Problem und ein Mapping-Problem nicht mit einer abgelaufenen Apple Distribution-Identität verwechselt.

Repository und Entschlüsselung: getrennte Zugangstests für CI

Git-Zugriff ist nicht gleich Signatur-Repository-Zugriff

Viele Teams testen den Quellcodezugriff und schließen daraus, dass auch match funktionieren müsse. Das ist falsch, sobald der Signaturspeicher ein separates Repository, einen anderen Branch, einen Objektspeicher oder eigene Zugangsdaten verwendet. Ein erfolgreiches git clone des Anwendungscodes bestätigt daher weder den richtigen Signatur-Repository-Zugriff noch die Berechtigung auf verschlüsselte Dateien.

Die fastlane-match-Dokumentation beschreibt unterschiedliche Speicher- und Authentifizierungsmodelle. Prüfen Sie deshalb unabhängig voneinander:

  • Repository-URL: https://<SIGNING_REPOSITORY_URL>
  • Branch: <SIGNING_BRANCH>
  • Team-Konfiguration: <TEAM_ID>
  • Speicherzugang: <STORAGE_TOKEN>
  • Entschlüsselungswert: <MATCH_PASSWORD>

Verwenden Sie diese Platzhalter nicht nur im Artikel, sondern auch in einer internen Diagnosevorlage. Ein echter Token oder ein echter Passwortwert gehört niemals in ein reproduzierbares Log.

Falscher Branch, falsches Team, falsches Passwort

Wenn der Speicher erreichbar ist, kann dennoch ein falscher Branch geladen werden. Das äußert sich oft so, als fehlten Profile oder Zertifikate. Prüfen Sie den Branch explizit und vergleichen Sie die erwartete Bundle-ID mit den im Signaturbestand abgelegten Assets.

Ein anderes Fehlerbild entsteht, wenn der CI-Benutzer lesen darf, aber nicht auf den benötigten Objektspeicher oder das Geheimnisverwaltungssystem zugreifen kann. Testen Sie die CI-Credentials deshalb in derselben Ausführungsumgebung wie den Build-Prozess, nicht nur in Ihrer interaktiven Shell.

Ein fehlgeschlagener Entschlüsselungsversuch ist wiederum kein Beleg für ein abgelaufenes Zertifikat. Prüfen Sie zunächst, ob <MATCH_PASSWORD> aus dem richtigen Secret stammt, ohne den Wert auszugeben. Wenn sich das Passwort geändert hat, müssen Sie die Wiederherstellung des bestehenden Bestands klären, bevor Sie neue Assets erzeugen.

Sicherheitsgrenze: Behandeln Sie Repository-Token, Deploy Keys, Speicher-Credentials und MATCH_PASSWORD als getrennte Geheimnisse. Löschen Sie sie aus CI-Ausgaben und rotieren Sie ein Secret, sobald es in einem ungefilterten Log sichtbar war.

Keychain und Signaturidentität: Zertifikatdatei gegen nutzbare Identität

Das Zertifikat allein reicht nicht

Eine Zertifikatdatei beschreibt den öffentlichen Teil der Identität. Für die Codesignatur benötigt der Prozess zusätzlich den passenden privaten Schlüssel. Apple erklärt die Beziehung zwischen Zertifikat, privatem Schlüssel und Signaturidentität in den offiziellen Hinweisen zur App-Signierung. Entscheidend ist also nicht, ob eine Zertifikatdatei auf dem Remote Mac liegt, sondern ob die Kombination aus Zertifikat und privatem Schlüssel in der verwendeten Keychain als vollständige Identität verfügbar ist.

Prüfen Sie zunächst, welche Identitäten der Build-Benutzer sieht:

security find-identity -v -p codesigning \
  <KEYCHAIN_PARAMETER>

Ersetzen Sie <KEYCHAIN_PARAMETER> durch die im Projekt verwendete Keychain-Option. Verwenden Sie keine reale Datei oder keinen realen Namen in einer öffentlich geteilten Diagnose. Wenn das Ergebnis keine erwartete Apple Distribution-Identität enthält, prüfen Sie als Nächstes, ob match tatsächlich in diese Keychain importiert hat oder eine andere Keychain verwendet.

Eine sichtbare Identität kann trotzdem unbrauchbar sein. Typische Ursachen sind:

  • Der private Schlüssel wurde nicht importiert.
  • Zertifikat und privater Schlüssel stammen aus unterschiedlichen Beständen.
  • Der CI-Prozess prüft eine andere Keychain als Ihre interaktive Sitzung.
  • Die Keychain ist nach einem Neustart gesperrt.
  • Der Build-Benutzer besitzt keine ausreichende Berechtigung für den Schlüssel.
  • Der Import wurde in einer temporären Umgebung durchgeführt und ist nach der Sitzung verschwunden.

Neustart und unbeaufsichtigter Zugriff

Wenn ein Remote Mac vor dem Neustart funktioniert und danach mit einer gesperrten Keychain scheitert, untersuchen Sie zuerst den Lebenszyklus der Keychain. Prüfen Sie, welcher Benutzer den Dienst startet, welche Keychain er verwendet und ob diese nach dem Neustart entsperrt werden kann. Führen Sie die Prüfung als derselbe Benutzer aus, der auch Archive und Export startet.

Vermeiden Sie es, pauschal alle Keychain-Berechtigungen zu lockern. Das verschiebt das Problem in Richtung eines größeren Geheimnisrisikos und erschwert später die Nachvollziehbarkeit. Ebenso ist eine dauerhaft geöffnete interaktive Anmeldung kein belastbarer Standard für CI. Besser ist eine dokumentierte, minimal berechtigte Keychain-Konfiguration, die Sie mit einem nicht veröffentlichenden Test-Archive prüfen.

Wenn Sie die Unterschiede zwischen lokaler und entfernter Umgebung untersuchen, vergleichen Sie mindestens aktive Xcode-Auswahl, Benutzerkonto, Keychain-Liste, Umgebungsvariablen und Build-Aufruf. Die fastlane-CI-Dokumentation ist dabei die Referenz für die Trennung von CI-Secrets und Build-Schritten.

Provisioning Profile und Target-Mapping: Identität ist nicht Zuordnung

Bundle ID, Team und Profile-Typ

Ein Provisioning Profile ist nur dann verwendbar, wenn es zum konkreten Target passt. Prüfen Sie für jedes Target einzeln:

  • Bundle ID beziehungsweise App-ID
  • Apple-Team
  • Profile-Typ für Entwicklung, Ad-hoc-Verteilung oder App-Store-Verteilung
  • zugeordnetes Zertifikat
  • benötigte Entitlements
  • Gültigkeit und Status im Entwicklerkonto

Apple beschreibt in der Dokumentation zur Verwaltung von Provisioning Profiles die Möglichkeiten zum Bearbeiten, Herunterladen und Löschen. Für die lokale Diagnose können Sie das installierte Profile auslesen:

security cms -D -i <PROVISIONING_PROFILE_PATH>

Verwenden Sie <PROVISIONING_PROFILE_PATH> als Platzhalter. Prüfen Sie die ausgegebenen Werte nicht nur gegen die Haupt-App, sondern gegen das Target, das im fehlgeschlagenen Archive tatsächlich gebaut wird.

Ein Profile kann existieren und trotzdem unpassend sein. Das passiert häufig bei App-Erweiterungen, Watch-Komponenten oder mehreren Apps, die denselben Signaturbestand verwenden. Ein Haupt-Target mit <BUNDLE_ID_APP> und eine Erweiterung mit <BUNDLE_ID_EXTENSION> benötigen nicht automatisch dasselbe Mapping. Die Profile-Namen dürfen deshalb nicht bloß nach dem Produktnamen ausgewählt werden.

readonly und fehlende Assets

readonly schützt einen CI-Lauf davor, während eines Builds neue Zertifikate oder Profile anzulegen. Es ersetzt aber keine administrative Einrichtung. Wenn das benötigte Profile im Signaturbestand fehlt, kann ein match readonly-Lauf es nicht für Sie erstellen oder reparieren.

Bei einem Fehler „Profile nicht gefunden“ unterscheiden Sie daher drei Fälle:

  1. Das Profile existiert im Entwicklerkonto nicht.
  2. Es existiert, ist aber nicht im verschlüsselten match-Bestand oder im richtigen Branch.
  3. Es ist installiert, wird aber vom Target oder von der Export-Konfiguration nicht ausgewählt.

Führen Sie die Einrichtung mit einem dafür vorgesehenen Administrationslauf durch und lassen Sie den CI-Lauf anschließend wieder mit readonly arbeiten. Überprüfen Sie vor dem nächsten Release, ob jedes Target ein explizites Mapping besitzt.

Diagnosebefund Wahrscheinlichere Ursache Nächster kontrollierter Schritt Nicht als Erstmaßnahme ausführen
Repository nicht erreichbar URL, Branch oder Speicher-Credential falsch Zugang im CI-Kontext getrennt testen Zertifikat widerrufen
Entschlüsselung schlägt fehl MATCH_PASSWORD oder Secret-Zuordnung falsch Secret-Quelle und Maskierung prüfen match nuke
Zertifikat sichtbar, private Schlüssel fehlt unvollständiger Import oder falsche Keychain Identität als Build-Benutzer prüfen neue Identität erzeugen
Profile vorhanden, Target lehnt es ab Bundle-ID-, Team- oder Entitlement-Mismatch Target-Mapping und Export-Ziel vergleichen alle Profile löschen
Lokales Archive erfolgreich, CI scheitert Umgebungs-, Benutzer- oder Xcode-Differenz gleichen Commit und Befehl verwenden lokale Einstellungen kopieren
Asset abgelaufen oder nicht wiederherstellbar kontrollierte Rotation erforderlich Auswirkungen auf Apps und Pipelines dokumentieren unkontrolliertes Neuaufsetzen

Lokaler Erfolg gegen Remote-Archive: gleiche Variablen erzwingen

Ein lokaler Xcode-Build kann automatisch signieren und dabei stillschweigend lokale Einstellungen, cached Assets oder eine bereits entsperrte Keychain verwenden. Ein Remote-Archive über die Kommandozeile hat diese Voraussetzungen möglicherweise nicht. Vergleichen Sie deshalb nicht nur das Ergebnis, sondern den vollständigen Ablauf.

Der robuste Vergleich sieht so aus:

  1. Verwenden Sie denselben Commit im lokalen und entfernten Lauf.
  2. Wählen Sie dieselbe Xcode-Installation und dieselbe aktive Entwicklerumgebung.
  3. Nutzen Sie dasselbe Scheme und dieselbe Configuration.
  4. Führen Sie match vor dem Build aus.
  5. Verwenden Sie denselben Archive-Befehl.
  6. Exportieren Sie mit derselben Export-Konfiguration.
  7. Prüfen Sie das Ergebnis vor einem Upload.

Die fastlane-Dokumentation zu match sollte dabei neben der CI-Konfiguration geöffnet bleiben. Besonders wichtig ist die Reihenfolge: Das Signatur-Asset muss verfügbar und importiert sein, bevor Xcode den Archive-Schritt ausführt.

Prüfen Sie zusätzlich, ob lokale automatische Signierung aktiv ist, während der Remote-Lauf ein explizites Profile erwartet. Diese beiden Modelle können unterschiedliche Entscheidungen treffen, obwohl Projektdateien und Quellcode identisch sind. Bei mehreren Targets muss die Export-Konfiguration jedes Profile mit dem korrekten Target verbinden.

Für die Beweissicherung reichen zunächst ein anonymisierter Abschnitt aus xcodebuild, der Exit-Status, die Build Settings für Code Signing, das aktive Scheme und die Ausgabe von security find-identity. Entfernen Sie Zertifikatsseriennummern nur dann nicht, wenn sie intern gebraucht werden; für externe Tickets sollten auch diese Werte reduziert oder anonymisiert werden.

Reparatur, Rotation oder Neuaufbau: die richtige Eingriffsstufe

Authentifizierung und Mapping reparieren

Bleibt das Asset gültig und ist nur der Zugriff, die Entschlüsselung, die Keychain oder das Target-Mapping fehlerhaft, reparieren Sie die Umgebung. Das ist die kleinste Eingriffsstufe. Dokumentieren Sie, welche Variable geändert wurde, welcher Benutzer den Test ausgeführt hat und ob ein Archive danach wieder möglich war.

Bei mehreren Bundle IDs sollten Sie eine Zuordnungstabelle im Repository pflegen. Sie muss für jedes Target das erwartete Profile, den Profile-Typ, die Zertifikatsklasse und die benötigten Entitlements ausweisen. So wird ein fehlendes Erweiterungsprofil nicht fälschlich als Problem der Haupt-App behandelt.

Abgelaufene oder veränderte Assets kontrolliert rotieren

Eine Rotation ist angebracht, wenn ein Zertifikat oder Profile abgelaufen ist, eine Berechtigung im Entwicklerkonto geändert wurde oder der private Schlüssel nicht mehr sicher verfügbar ist. Halten Sie vor dem Eingriff fest, welche Apps, Targets, Veröffentlichungsaufgaben und CI-Pipelines das betroffene Asset verwenden.

Ein Zertifikatswechsel kann nicht nur einen einzelnen Build betreffen. Er kann auch parallele Release-Zweige, Erweiterungen und bereits vorbereitete Export-Prozesse beeinflussen. Planen Sie deshalb zuerst einen nicht dringenden Archive- und Export-Test, bevor Sie einen zeitkritischen Store-Upload ausführen.

match nuke nur mit dokumentiertem Einflussbereich

match nuke entfernt Signaturmaterial aus dem von match verwalteten Bestand und kann dadurch mehrere Verteilungsketten treffen. Die offizielle Dokumentation zu match nuke ist deshalb vor jeder Ausführung zu lesen. Der Befehl ist kein allgemeines „Reparieren“-Kommando.

Erwägen Sie ihn erst, wenn Sie bestätigt haben, dass die vorhandenen Assets nicht wiederherstellbar sind und der Einflussbereich dokumentiert ist. Sichern Sie vorher die Zuordnung von Zertifikaten, Profilen, Apps und Release-Pipelines. Prüfen Sie danach nicht nur einen grünen CI-Schritt, sondern ein vollständiges Archive, einen Export und die Validierung vor dem Upload.

Wiederherstellungsmeilensteine für einen Remote Mac

Behandeln Sie die Wiederherstellung wie eine kurze Zeitlinie:

  • Diagnose: Log anonymisieren, Exit-Status sichern und Fehlerlage bestimmen.
  • Zugriff: Repository, Branch, Team-Konfiguration und Entschlüsselung getrennt testen.
  • Identität: Keychain, privater Schlüssel und Apple Distribution-Identität als Build-Benutzer prüfen.
  • Zuordnung: Profile, Bundle IDs, Targets und Entitlements abgleichen.
  • Reproduktion: gleicher Commit, gleiches Scheme, gleiche Configuration und gleicher Archive-Befehl.
  • Abnahme: Export und Upload-Vorprüfung nach einem Neustart des Remote Mac wiederholen.

Die letzte Stufe ist wichtig: Ein Build, der nur in einer offenen Sitzung funktioniert, ist noch keine stabile CI-Lösung. Der Remote Mac muss die Signaturkette auch nach einem Neustart mit dem vorgesehenen Benutzer und der vorgesehenen Keychain reproduzierbar herstellen können. Wenn die Umgebung häufig zurückgesetzt wird, verlieren Sie sonst den Vorteil zentral verwalteter Assets und verbringen Zeit mit wiederkehrenden Import- und Entsperrungsfehlern.

Wenn Sie für diese Prüfung eine dauerhaft erreichbare Umgebung benötigen, können Sie die verfügbaren Remote-Mac-Optionen von VMSPIN anhand Ihrer geplanten Testdauer vergleichen. Für eine Kostenprüfung finden Sie die aktuellen VMSPIN-Mietmodelle; entscheidend für diesen Anwendungsfall ist jedoch nicht allein der Tarif, sondern ob Keychain, Build-Benutzer und Signaturbestand zwischen den Läufen nachvollziehbar erhalten bleiben.

Ein temporär eingerichteter Rechner hat gegenüber einem dauerhaft verwalteten Remote Mac drei reale Nachteile: Die Keychain kann nach einer Neuinitialisierung fehlen, CI-Secrets müssen wiederholt eingerichtet werden und ein erfolgreicher lokaler Test beweist nicht die Wiederholbarkeit nach einem Neustart. Wenn Ihr Problem genau aus solchen Unterbrechungen entsteht, ist ein eigener, kontrolliert erreichbarer Mac für einen nicht dringenden Release-Zweig die sinnvollere Gegenprobe. Mieten Sie bei VMSPIN zunächst eine Umgebung für diesen Wiederherstellungstest und akzeptieren Sie sie erst, wenn Archive und Export auch nach dem Neustart mit derselben Signaturkette funktionieren.