Symptom: fastlane match kann das private Signierungs-Repository auf dem Remote Mac nicht lesen oder die geladenen Materialien nicht verwenden.
Schnellste Lösung: Prüfen Sie zuerst den Repository-Zugriff, danach MATCH_PASSWORD, Apple-Kontozugriff und zuletzt Zertifikat, privaten Schlüssel, Provisioning Profile und Keychain. Für CI und unbeaufsichtigte Builds verwenden Sie readonly; erstellen oder widerrufen Sie nicht vorschnell Zertifikate.

Dieser Leitfaden richtet sich an Sie, wenn Sie fastlane match erstmals auf einem Remote Mac einrichten und Signierungsmaterial nicht abrufen können.
Er hilft kleinen Teams, die Schreibrechte für ein gemeinsames Repository begrenzen und Zuständigkeiten klären müssen.
Auch wenn nach einem Umzug auf einen neuen Mac oder in eine CI-Umgebung der Signierungsablauf scheitert, finden Sie hier Prüfungen vom Zugang bis zum Archive.

fastlane match: private Repository-Fehler nach Ursache trennen

Behandeln Sie einen fehlgeschlagenen Lauf nicht pauschal als „Signing-Fehler“. fastlane match liest Signierungsmaterial aus einer konfigurierten Speicherquelle. Der Zugang zu dieser Quelle und die Entschlüsselung der gespeicherten Inhalte sind getrennte Vorgänge. Auch eine erfolgreiche Synchronisierung belegt noch nicht, dass Xcode eine passende Signieridentität findet.

Die Dokumentation von fastlane zu match beschreibt Speicheroptionen sowie die Verwendung von readonly und CI. Ordnen Sie die erste aussagekräftige Fehlermeldung einer dieser Ebenen zu:

  • Repository nicht erreichbar: Prüfen Sie Git-URL, Verbindung, SSH-Schlüssel, HTTPS-Zugang oder Berechtigungsumfang.
  • Repository erreichbar, Entschlüsselung schlägt fehl: Prüfen Sie MATCH_PASSWORD und seine Bereitstellung im Build-Kontext.
  • Materialien geladen, Signierung scheitert: Untersuchen Sie Zertifikat, privaten Schlüssel, Provisioning Profile, Build-Ziel und Keychain.
  • Apple-Konto- oder Portalprüfung schlägt fehl: Prüfen Sie Kontoberechtigung und den konkreten Portalvorgang getrennt von der lokalen Keychain.

Wie erkennen Sie, ob der Klon des privaten Repositorys scheitert?
Ein Verbindungs- oder Autorisierungsfehler vor dem Abruf weist auf URL, Netzwerk oder Git-Anmeldedaten hin. Mit git ls-remote können Sie unabhängig vom fastlane-Aufruf testen, welche Referenzen das entfernte Repository für den aktuellen Prozess sichtbar macht. Der Befehl bestätigt nicht, dass verschlüsselte Dateien entschlüsselt werden können. Dafür ist eine separate Prüfung erforderlich. Die Git-Dokumentation zu git ls-remote beschreibt die Anzeige der sichtbaren Referenzen.

Führen Sie den Test unter derselben macOS-Benutzeridentität aus, die auch den Build startet. Ein erfolgreicher Aufruf in Ihrem interaktiven Terminal beweist nicht, dass ein CI-Runner, Dienstbenutzer oder Hintergrundprozess dieselben Schlüssel und Umgebungsvariablen sieht. Vergleichen Sie die bereinigte fastlane-Fehlermeldung mit dem Ergebnis des Git-Tests. So vermeiden Sie, schon beim ersten Hinweis Zertifikate oder Profile zu verändern.

Entfernen Sie Repository-URLs, Hostnamen, Schlüssel, Token, Zertifikatskennungen, lokale Pfade und Geheimnisse aus Diagnoseausgaben, bevor Sie Protokolle teilen. Auch ein vermeintlich harmloser Terminalmitschnitt kann interne Zugriffswege offenlegen.

Neuer Remote Mac und vorhandener Entwicklerrechner

Wenn der eigene Rechner das Repository lesen kann, der neu eingerichtete Remote Mac aber nicht, ist die naheliegende Ursache ein anderer Zugang oder eine abweichende ausführende Identität. Das ist zunächst kein Hinweis auf defekte Signierungsdateien.

Git-Zugang unter der Build-Identität prüfen

Prüfen Sie, ob der Build per SSH oder HTTPS zugreift. Die tatsächlich verwendete URL muss zur eingerichteten Authentifizierung passen. Ein HTTPS-Token hilft nicht bei einer SSH-Adresse; ein SSH-Schlüssel wird nicht automatisch verwendet, wenn Git eine HTTPS-Verbindung öffnet.

Bei SSH kontrollieren Sie den konfigurierten Schlüssel, den Schlüsselagenten und die Zuordnung zum Repository. Die Anleitung zum Testen einer SSH-Verbindung beschreibt einen Verbindungstest. Ein erfolgreicher allgemeiner Test belegt jedoch nicht, dass das verwendete Konto auf genau dieses Repository zugreifen darf. Ergänzen Sie ihn deshalb durch git ls-remote mit der in der Lane konfigurierten Adresse.

Ein Deploy Key kann den Zugriff auf ein bestimmtes Repository begrenzen. Prüfen Sie, ob der Schlüssel dort hinterlegt ist und ob sein Umfang für den benötigten Vorgang ausreicht. Die Dokumentation zu Deploy Keys erläutert diese Zugriffsmöglichkeit. Verwenden Sie nicht das private Konto eines Teammitglieds als dauerhafte Abkürzung. Sonst bleiben Zuständigkeit und späterer Entzug des Zugriffs unnötig unklar.

Bei HTTPS prüfen Sie, ob der Runner das vorgesehene Token im richtigen Job-Kontext erhält. Unterscheiden Sie dabei das Token für den Repository-Zugriff von MATCH_PASSWORD: Das Token authentifiziert den Git-Zugriff, während das Kennwort dem Zugriff auf verschlüsselte match-Daten dient. Speichern Sie keines davon im Repository, in Skripten oder in der Kommandozeilenhistorie.

Welche Zugangsdaten verwendet GitHub Actions beim Abruf?
Das hängt davon ab, wie der Workflow und seine Secrets eingerichtet sind. Prüfen Sie, welche Geheimnisse im betreffenden Job verfügbar sind und ob der Lauf im erwarteten Repository-Kontext stattfindet. Die Dokumentation zu Secrets in GitHub Actions beschreibt deren Verfügbarkeit und Einschränkungen. Geben Sie Geheimnisse nicht in Protokollen aus und stellen Sie sie nicht pauschal allen Jobs zur Verfügung.

Schreibrechte im Team begrenzen

Klären Sie die Zuständigkeiten zwischen Entwicklern, Repository-Verantwortlichen und CI-Wartenden. Ein Build muss Signierungsmaterial üblicherweise lesen können, braucht aber nicht automatisch Schreibrechte für das zentrale Repository. Für unbeaufsichtigte und wiederholbare CI-Läufe empfiehlt fastlane readonly. Schreibzugriff sollte nur für ausdrücklich autorisierte Wartungsvorgänge verfügbar sein, etwa wenn Signierungsmaterial kontrolliert aktualisiert werden muss.

Der Vorteil einer schreibgeschützten CI-Konfiguration: Ein regulärer Build kann nicht eigenmächtig zentrale Materialien ändern. Der Nachteil: Fehlt ein benötigtes Material oder muss etwas aktualisiert werden, kann der Job es nicht selbst eintragen. Dafür ist ein getrennter Wartungsschritt erforderlich. Diese Einschränkung ist gewollt und kein Grund, dem täglichen Build pauschal Schreibrechte zu geben.

Erreichbares Repository, aber MATCH_PASSWORD schlägt fehl

Wenn git ls-remote das Repository erreicht und fastlane match Inhalte abruft, die Entschlüsselung aber scheitert, ändern Sie nicht vorsorglich den Git-Schlüssel. Prüfen Sie stattdessen, ob der Build das richtige MATCH_PASSWORD aus dem vorgesehenen Geheimnisspeicher erhält.

Kontrollieren Sie den Variablennamen in der Lane und im Runner. Achten Sie auf Unterschiede zwischen lokalem Terminal, Remote-Mac-Sitzung und CI-Job. Eine Variable kann in einer interaktiven Shell gesetzt sein, aber dem Hintergrundprozess fehlen. Nach einem Umzug, einer Rotation oder einer Änderung des Workflow-Kontexts kann außerdem ein anderer Wert bereitgestellt werden als erwartet.

Prüfen Sie, ob die Variable vorhanden ist, ohne ihren Inhalt auszugeben. Wenn Sie das Geheimnis neu hinterlegen müssen, nutzen Sie den dafür vorgesehenen Geheimnisspeicher und beschränken Sie die Freigabe auf den Job, der es benötigt. Schreiben Sie das Kennwort weder in die Repository-Konfiguration noch in Shell-Befehle, die in der Historie landen. Es gehört auch nicht in öffentlich zugängliche oder allgemein geteilte Build-Protokolle.

Wie unterscheiden Sie einen Kennwortfehler von einer Git-Authentifizierungsstörung?
Bei fehlender Git-Autorisierung scheitert der Zugriff auf das Repository, bevor die verschlüsselten Inhalte verarbeitet werden. Ein falsches MATCH_PASSWORD wird erst beim Entschlüsseln relevant. Testen Sie daher zuerst den Repository-Zugriff mit der tatsächlich verwendeten Adresse und prüfen Sie danach die Geheimnisbereitstellung. Wenn Sie beide Ebenen gleichzeitig ändern, erschweren Sie die Ursachenanalyse und wissen anschließend nicht, welche Änderung den Fehler behoben hat.

Geladene Materialien ohne verwendbare Signieridentität

Ein erfolgreicher match-Lauf bedeutet nicht automatisch, dass Xcode signieren kann. Für eine gültige Code-Signatur müssen Zertifikat und zugehöriger privater Schlüssel zusammen verfügbar sein. Apples Technotiz zu Code-Signing-Zertifikaten erläutert die Rolle von Zertifikat und Signieridentität. Prüfen Sie in der Keychain der Build-Identität, ob das Zertifikat zusammen mit dem zugehörigen privaten Schlüssel vorhanden ist und dem Prozess zur Verfügung steht.

Kontrollieren Sie danach das Provisioning Profile. Es muss zum App-Ziel, zur Signieridentität und zu den verwendeten Fähigkeiten passen. Die Apple-Dokumentation zu Provisioning Profiles beschreibt die Bedingungen, die ein Profil zusammenführt. Falls es aktualisiert werden muss, folgen Sie Apples Ablauf zum Bearbeiten, Herunterladen oder Löschen von Profilen.

Trennen Sie diese lokalen Prüfungen von einer Apple-Konto- oder Portalfehlermeldung. Ein fehlender privater Schlüssel in der Keychain wird nicht durch eine erneute Anmeldung beim Entwicklerkonto behoben. Umgekehrt belegt ein abgelehnter Portalzugriff nicht, dass ein lokales Zertifikat defekt ist. Halten Sie fest, welcher Vorgang scheitert: Abruf aus dem match-Speicher, Entschlüsselung, Installation in die Keychain, Profilprüfung oder Kommunikation mit dem Entwicklerkonto.

Was prüfen Sie, wenn match erfolgreich war, Xcode aber kein Zertifikat findet?
Prüfen Sie zuerst die Signieridentität in der Keychain, die der Build tatsächlich verwendet. Stellen Sie fest, ob der private Schlüssel zum Zertifikat gehört. Vergleichen Sie anschließend Team, App-Kennung, Fähigkeiten und Profil des betroffenen Ziels. Planen Sie eine Erneuerung erst, wenn diese Prüfungen auf einen fehlenden oder nicht mehr gültigen Eintrag hinweisen. Widerrufen oder löschen Sie kein Zertifikat, bevor Sie Auswirkungen auf andere Builds und einen Rückweg geklärt haben.

Entscheidungshilfe für readonly und Wartungsläufe

Nutzen Sie die folgende Entscheidungsliste. Markieren Sie die passende Bedingung und folgen Sie dem genannten Pfad. Ändern Sie nicht mehrere Ebenen gleichzeitig: Sonst bleibt unklar, welche Maßnahme den Fehler tatsächlich behoben hat.

  • [ ] Der Lauf ist ein regulärer CI- oder unbeaufsichtigter Build. Verwenden Sie readonly. Wenn ein benötigtes Material fehlt, stoppen Sie den Build und lassen Sie es durch einen autorisierten Wartenden bereitstellen. Erteilen Sie dem täglichen Job nicht vorsorglich Schreibrechte.
  • [ ] Sie müssen Signierungsmaterial ausdrücklich erstellen oder aktualisieren. Verwenden Sie einen getrennten Wartungslauf mit den erforderlichen Schreibrechten. Führen Sie diesen Vorgang nach dem Freigabeprozess Ihres Teams aus; setzen Sie den normalen CI-Build nicht dauerhaft in einen schreibenden Modus.
  • [ ] Der Repository-Test scheitert. Korrigieren Sie zuerst URL, Authentifizierung oder Berechtigungsumfang. Ändern Sie MATCH_PASSWORD und Zertifikate nicht, solange der Speicher nicht erreichbar ist.
  • [ ] Der Repository-Zugriff gelingt, die Entschlüsselung jedoch nicht. Prüfen Sie die Bereitstellung von MATCH_PASSWORD in genau diesem Job. Tauschen Sie weder Git-Schlüssel noch Zertifikate aus, solange dafür kein eigener Befund vorliegt.
  • [ ] Abruf und Entschlüsselung gelingen, aber die Signierung scheitert. Untersuchen Sie Keychain, privaten Schlüssel, Provisioning Profile und App-Ziel. Erzeugen Sie keine neue Identität, bevor Sie die bestehende geprüft haben.
  • [ ] Apple-Konto oder Portal lehnt eine Anfrage ab. Prüfen Sie Kontoberechtigung und den betroffenen Portalvorgang getrennt von Git, Kennwort und lokalen Signierungsmaterialien.

Sind mehrere Kästchen zutreffend, bearbeiten Sie sie in dieser Reihenfolge: zuerst Repository-Zugriff, dann Entschlüsselung, danach lokale Signieridentität und zuletzt Portalzugriff. Ändern Sie nach jeder erfolgreichen Teilprüfung nur die nächste fehlerhafte Ebene. So behalten Sie eine nachvollziehbare Diagnose und können eine unbeabsichtigte Änderung leichter zurücknehmen.

Schreibrechte bei einem regulären Build können Wartungsschritte vereinfachen, vergrößern aber den Umfang möglicher Repository-Änderungen. Ein getrennter Wartungslauf verlangt eine klare Zuständigkeit und zusätzliche Koordination, hält die alltägliche Build-Berechtigung jedoch enger. Wenn Ihr Team noch nicht festgelegt hat, wer Änderungen freigibt und wie eine Rückkehr zum vorherigen Zustand erfolgt, klären Sie diesen Ablauf, bevor Sie den CI-Job erweitern.

Reparatur mit einem echten Build bestätigen

Nehmen Sie den Fehler nicht allein deshalb als behoben an, weil fastlane match nicht mehr abbricht. Prüfen Sie die gesamte Signierungskette stufenweise. So erkennen Sie, ob der Zugriff wieder funktioniert oder lediglich eine spätere Fehlermeldung sichtbar geworden ist.

  1. Build-Identität bestimmen. Halten Sie fest, welcher Benutzer und welcher Runner den Job starten. Prüfen Sie, ob Schlüssel und Geheimnisse genau in diesem Kontext verfügbar sind.
  2. Repository-Zugriff nachweisen. Testen Sie den Git-Zugriff mit der konfigurierten URL. Bewahren Sie nur eine bereinigte Erfolgs- oder Fehlermeldung auf.
  3. Entschlüsselung bestätigen. Starten Sie den vorgesehenen match-Ablauf mit dem Geheimnis aus dem korrekten Speicher. Protokollieren Sie dessen Wert nicht.
  4. Signieridentität prüfen. Verifizieren Sie Zertifikat und zugehörigen privaten Schlüssel in der Keychain, auf die der Build zugreift.
  5. Profil und Ziel abgleichen. Kontrollieren Sie App-Ziel, Team, Signieridentität, Profil und benötigte Fähigkeiten.
  6. Build und Archive ausführen. Bauen und archivieren Sie das tatsächliche Projekt. Halten Sie die Nachweise für Repository-Zugriff, Signieridentität und Archive getrennt fest.

Vor dem Widerruf, Austausch oder Bereinigen von Zertifikaten und Keychain-Einträgen klären Sie, welche weiteren Projekte oder Veröffentlichungsabläufe davon abhängen. Sichern Sie den erforderlichen Zustand und definieren Sie einen Rückweg. Ein erfolgreicher Abruf aus dem match-Repository belegt nur, dass die Materialien lesbar sind. Er beweist nicht, dass der vollständige Veröffentlichungsablauf funktioniert.

Remote Mac als Build-Umgebung abwägen

Liegt die Ursache nicht bei Git oder den Geheimnissen, sondern fehlt Ihnen eine geeignete macOS-Umgebung für Xcode-Signierung und Archive, treffen Sie die Infrastrukturentscheidung getrennt von der Fehlerbehebung. Ein eigener Mac ist häufig sinnvoll, wenn Sie dauerhaft hohe Build-Auslastung oder direkten Zugriff auf physische Schnittstellen benötigen. Ein CI-Dienst kann für standardisierte Abläufe passen, setzt aber eine sorgfältige Verwaltung von Geheimnissen und Keychain voraus. Bei wechselndem Bedarf kann ein gemieteter Remote Mac den Kauf zusätzlicher Build-Hardware vermeiden. Prüfen Sie dafür Netzwerkzugriff, Datenschutz, Wiederherstellung und benötigte Werkzeuge vorab.

Weitere Informationen finden Sie auf der deutschsprachigen MACCOME-Seite und in der Übersicht zum Bestellen eines Mac mini. Entscheiden Sie anhand von Auslastung und Zugriff: Bei dauerhaft schweren Builds oder zwingend benötigten physischen Geräten ist Miete nicht automatisch die passende Wahl. Wenn Sie dagegen zeitweise eine vollständige macOS-Umgebung für Xcode-Signierung und reproduzierbare Archive benötigen, kann ein Remote Mac praktischer sein als ein zusätzlicher lokaler Build-Rechner. Prüfen Sie die Umgebung mit Ihrem Repository-Zugriff, Ihrer Geheimnisverwaltung und einem echten Archive-Lauf, bevor Sie den Veröffentlichungsablauf dorthin verlagern.