Der Workflow läuft unverändert weiter, aber der Cloud-Rollenwechsel wird plötzlich abgelehnt: GitHub Actions OIDC defekt bedeutet nicht automatisch, dass Ihr YAML geändert werden muss.

Schnellste Lösung: Lesen Sie zuerst das tatsächlich ausgestellte OIDC-Token aus, vergleichen Sie iss, aud, sub, repository_id und owner_id mit der Cloud-Vertrauensregel und ändern Sie erst danach die Bedingung. Führen Sie keine dauerhaften Cloud-Schlüssel als vorschnellen Rückfall ein. Die Änderung des unveränderlichen Subject-Formats für bestimmte neue oder umgestellte Repositories trat laut GitHub-Dokumentation nach dem 15.07.2026 in Kraft; diese Angabe wurde am 11.09.2026 anhand der offiziellen GitHub-Referenz geprüft.

Diese Anleitung richtet sich an Plattform- und IT-Teams, die GitHub Actions OIDC und Cloud-Rollen verwalten.
Sie ist ebenso für Verantwortliche von Self-hosted Runnern, Xcode-Builds und Produktionsfreigaben gedacht.
Auch Sicherheitsverantwortliche vor einer Repository-Umbenennung, einem Transfer oder einer zentralen OIDC-Template-Änderung finden hier ein Prüfverfahren.

01

Der erste Messwert ist der tatsächliche Subject Claim

Wenn GitHub Actions OIDC defekt erscheint, beginnen Sie nicht mit einer Änderung am Workflow. Der wichtigste Messwert ist sub. Er beschreibt, für welche GitHub-Actions-Identität der Token ausgestellt wurde. Der Cloud-Anbieter akzeptiert den Token nur, wenn seine Vertrauensregel genau zu den erhaltenen Claims passt.

Die offizielle GitHub-OIDC-Referenz bestätigt, dass der Token unter anderem Aussteller, Zielgruppe und Subject enthält. In der Praxis sollten Sie mindestens diese Felder protokollieren:

  • iss: Aussteller des Tokens.
  • aud: Zielgruppe, für die der Token bestimmt ist.
  • sub: Subject der Workflow-Identität.
  • repository_id: numerische Repository-Identität.
  • owner_id: numerische Identität der Organisation oder des Besitzers.
  • Repository, Referenz, Environment oder wiederverwendbarer Workflow, sofern diese Angaben im Claim enthalten sind.

Entscheidend ist die Reihenfolge: Token aus einem kontrollierten Testlauf auslesen, sensible Werte redigieren und erst dann mit der Cloud-Policy vergleichen. Der Repository-Name allein reicht nicht aus. Ein Name kann sich ändern, während eine numerische ID die Identität stabiler beschreibt. Umgekehrt kann ein Transfer oder eine Einstellung zur unveränderlichen Subject-Struktur dazu führen, dass die bisherige Vertrauensbedingung nicht mehr passt.

Alte, neue und benutzerdefinierte Subject-Strukturen

Prüfpunkt Bisherige Struktur Unveränderliche Struktur Benutzerdefinierte Vorlage
Hauptsignal Repository- und Workflow-Kontext nach bisherigem Format Enthält zusätzlich owner_id und repository_id Von der konfigurierten GitHub-Vorlage bestimmt
Typischer Auslöser Bestehendes Repository ohne Opt-in Neues Repository nach dem 15.07.2026 oder aktivierte Einstellung Organisation definiert eigenes Subject-Schema
Hauptrisiko Vertrauensregel erwartet anderes Kontextformat Exakte sub-Zeichenkette stimmt nicht mehr Mehrere Teams interpretieren die Vorlage unterschiedlich
Erste Maßnahme Realen Token mit der Policy vergleichen Neue Claim-Struktur dokumentieren und Policy gezielt anpassen Vorlage, betroffene Repositories und Cloud-Policies gemeinsam prüfen

Die Tabelle ist ein Diagnosemodell, keine Erlaubnis, eine beliebige Wildcard einzusetzen. GitHub bestätigt, dass nach dem 15.07.2026 erstellte Repositories standardmäßig die unveränderliche Form verwenden können, während ältere Repositories ihr bisheriges Format behalten, sofern sie nicht aktiv umgestellt werden. Bei Umbenennung oder Transfer kann ebenfalls ein Wechsel relevant werden. Der genaue Geltungsbereich für GitHub Enterprise Server muss separat anhand der offiziellen Produktdokumentation geprüft werden.

Warum kann sich die OIDC-Anmeldung nach einer Repository-Umbenennung ändern?
Weil die Cloud nicht den sichtbaren Namen, sondern die vom Token übermittelte Identität bewertet. Nach einer Umbenennung, einem Transfer oder einer Template-Änderung kann sub anders aufgebaut sein. Lesen Sie deshalb einen neuen Token und vergleichen Sie ihn mit der bisher erlaubten Zeichenfolge, statt den alten Repository-Namen in die Policy einzusetzen.

Achtung: Speichern Sie keinen vollständigen Produktions-Token in einem Ticket. Ein OIDC-Token ist kurzlebig, kann aber trotzdem interne Repository-, Organisations- und Zielinformationen offenlegen. Für die Dokumentation genügen redigierte Claims und ein Hash oder eine Versionskennung der Policy.

02

Vertrauen wird an der Cloud-Seite repariert

Ein Workflow kann korrekt laufen und trotzdem an der Cloud-STS, am internen Gateway oder an der Rollenannahme scheitern. Der Fehler liegt dann nicht zwingend in GitHub Actions. Prüfen Sie, ob die Gegenseite auf eine vollständige sub-Zeichenkette, eine Branch-Bedingung, ein Environment, eine Zielgruppe oder einen wiederverwendbaren Workflow abgleicht.

Die häufigsten Fehlermuster sind:

  • aud stimmt nicht mit der in der Cloud erwarteten Zielgruppe überein.
  • sub enthält ein Environment, während die Policy nur den Branch berücksichtigt.
  • Die Policy erlaubt einen alten Repository-Namen.
  • Eine Organisation hat eine OIDC-Vorlage aktiviert, aber nur einen Teil der Rollen aktualisiert.
  • Ein wiederverwendbarer Workflow wird als anderer Identitätskontext behandelt.
  • Der Token wird bei der falschen Cloud-Aktion oder mit einer falschen Zielgruppe angefordert.

Die OIDC-REST-API-Dokumentation von GitHub ist für die Prüfung der verfügbaren API-Schnittstelle und ihrer Berechtigungsgrenzen maßgeblich. Sie sollte zusammen mit dem konkreten Token und der aktiven Cloud-Policy gelesen werden. Ein allgemeiner Blogbeitrag oder eine Fehlermeldung ohne Claim-Auszug reicht für eine Produktionsfreigabe nicht aus.

Eine minimale Diagnose in fünf Schritten

  1. Fehlerlauf isolieren: Verwenden Sie ein nicht produktives Repository oder einen kontrollierten Branch. Lassen Sie nur den betroffenen Authentifizierungsschritt laufen.
  2. Token-Anforderung prüfen: Stellen Sie sicher, dass der betroffene Job die erforderliche OIDC-Berechtigung besitzt. Erteilen Sie diese Berechtigung nicht pauschal auf Workflow- oder Organisationsebene.
  3. Claims redigiert erfassen: Erfassen Sie iss, aud, sub, repository_id und owner_id. Entfernen Sie Tokenwert, Kontonamen, Rollen-ARNs und interne Ressourcenkennungen.
  4. Cloud-Policy versionieren: Exportieren Sie die aktive Vertrauensbedingung. Markieren Sie, ob sie auf vollständigem sub, Branch, Environment, Audience oder Workflow-Kontext beruht.
  5. Nur die kleinste Abweichung korrigieren: Ändern Sie die Bedingung passend zum beobachteten Claim. Öffnen Sie nicht gleichzeitig Branch-, Repository- und Organisations-Wildcards.

Die Korrektur gehört normalerweise an die Seite, an der die Identitätsbedingung nicht mehr stimmt. Nur den Workflow zu bearbeiten, während der Cloud-Anbieter weiterhin den alten sub erwartet, behebt die Ursache nicht. Umgekehrt kann eine Cloud-Policy-Änderung wirkungslos bleiben, wenn der Workflow die falsche Audience oder kein Environment verwendet.

03

Der Änderungsumfang muss vorab messbar sein

Eine zentrale OIDC-Vorlage kann viele Repositories, Environments und Rollen betreffen. Erstellen Sie daher vor der Änderung eine Liste der Abhängigkeiten. Dazu gehören produktive und nicht produktive Workflows, wiederverwendbare Workflows, Cloud-Rollen, Freigabestufen und Self-hosted Runner.

Was muss vor einer Template- oder Repository-Änderung erfasst werden?
Erfassen Sie pro Repository den aktuellen Subject-Typ, die verwendeten Environments, die erlaubten Branches, die Cloud-Rolle und den verantwortlichen Dienst. Ergänzen Sie, ob ein Mac-Build, eine App-Veröffentlichung oder nur ein Cloud-Arbeitsschritt betroffen ist. So erkennen Sie, ob eine scheinbar kleine Claim-Änderung mehrere Produktionspipelines gleichzeitig unterbricht.

Unterscheiden Sie drei Fälle:

  1. Neues Repository: Die Standardstruktur kann bereits die unveränderlichen Angaben von Besitzer und Repository enthalten.
  2. Bestehendes Repository mit aktivem Opt-in: Das alte Format kann durch eine bewusste Einstellung ersetzt worden sein.
  3. Organisation mit zentraler Vorlage: Ein Administrator kann das Subject-Schema für mehrere Repositories beeinflussen.

Diese Fälle dürfen nicht in einer Sammeländerung behandelt werden. Ein Test-Repository sollte zuerst die erlaubte Struktur verwenden. Danach testen Sie ein bestehendes Repository, ein Environment und einen wiederverwendbaren Workflow. Erst wenn diese Kombinationen dokumentiert sind, sollte die Anpassung auf produktive Rollen ausgedehnt werden.

Vor- und Nachteile der Reparaturvarianten

Eine exakte sub-Bedingung bietet die stärkste Eingrenzung, verursacht aber bei legitimen Repository- oder Workflow-Änderungen Pflegeaufwand. Eine Bedingung auf Repository-ID und Owner-ID ist gegenüber bloßen Namen robuster, muss aber zum tatsächlichen Cloud-Produkt und dessen Claim-Unterstützung passen. Eine breite Wildcard ist schnell, aber sicherheitlich schwer zu begründen.

Die zentrale Regel lautet: Die Policy darf nur die Identitäten akzeptieren, die diese konkrete Rolle benötigen. Eine Übergangsregel kann zeitlich begrenzt werden. Sie sollte eine Ablaufbedingung, einen Verantwortlichen und einen dokumentierten Rückbau besitzen. „Es funktioniert wieder“ ist kein ausreichender Nachweis.

04

Berechtigungen bleiben enger als die Fehlerbehebung

Eine OIDC-Reparatur darf nicht zu einer allgemeinen Berechtigungserweiterung werden. Der betroffene Job benötigt möglicherweise id-token: write, aber daraus folgt nicht, dass alle Jobs des Workflows oder alle Pull Requests Cloud-Zugriff erhalten müssen.

Prüfen Sie mindestens diese Grenzen:

  • OIDC-Berechtigung nur im erforderlichen Job.
  • contents-Zugriff so niedrig wie möglich.
  • Produktions-Environment mit erforderlicher Freigabe.
  • Branch- und Tag-Bedingungen weiterhin aktiv.
  • Nicht vertrauenswürdige Pull Requests ohne Produktionsrolle.
  • Cloud-Rolle nur mit den tatsächlich benötigten Aktionen.
  • Kurzlebiger Cloud-Token statt dauerhaftem Cloud-Schlüssel.
  • Protokollierung der Rollenannahme und der abgelehnten Versuche.

Kann GitHub Actions OIDC einen Apple-Signaturschlüssel ersetzen?
Nein. OIDC kann bei einem unterstützten Cloud-Dienst einen kurzlebigen Zugriffstoken beziehen. Daraus folgt weder, dass Apple OIDC als Ersatz für ein Signaturzertifikat akzeptiert, noch dass ein App-Store-Connect-API-Schlüssel entfallen kann. Für App Store Connect beschreibt Apple weiterhin die Erstellung und Verwendung von API-Schlüsseln für die App-Store-Connect-API. Apple dokumentiert außerdem die Eigenschaften von Cloud-Managed Certificates. Diese Identitäten sind getrennt zu verwalten.

Damit entstehen mindestens vier verschiedene Geheimnis- und Identitätstypen:

  • GitHub-Actions-OIDC-Token.
  • Kurzlebiger Token des Cloud-Anbieters.
  • App-Store-Connect-API-Schlüssel.
  • Apple-Entwicklungs-, Distributions- oder Developer-ID-Signaturidentität.

Ein Fehler in der ersten Kategorie rechtfertigt nicht, die vierte Kategorie in denselben Job zu legen. Für Produktionssignierung sollte die vertrauenswürdige Mac-Umgebung separat behandelt werden. Ein Cloud-Role-Token darf nicht automatisch Zugriff auf das Signatur-Keychain erhalten.

05

Self-hosted Runner brauchen eine eigene Vertrauensgrenze

Ein Self-hosted Runner ist kein neutraler Vermittler. Er führt Code aus, der durch Workflow- und Repository-Berechtigungen bestimmt wird. Bei Pull Requests aus nicht vertrauenswürdigen Quellen, gemeinsam genutzten Workspaces und persistenten Keychains können sich Risiken über den eigentlichen Job hinaus auswirken.

Die GitHub-Sicherheitsdokumentation für Self-hosted Runner warnt ausdrücklich vor den besonderen Risiken solcher Runner. Für einen iOS-Build sollten Sie daher Cloud-Zugriff, Xcode-Build und Produktionssignierung nicht als eine einzige Berechtigungsstufe behandeln.

Wie isolieren Sie Cloud-Rechte und Signaturrechte auf einem Remote-Mac?
Trennen Sie zunächst die Runner-Zuordnung. Ein allgemeiner Build-Runner darf Cloud-Artefakte erzeugen, aber keine Produktions-Keychain entsperren. Ein dedizierter Signierungsrunner verarbeitet nur freigegebene Artefakte aus einem kontrollierten Workflow. Nach jedem Auftrag werden Workspace, temporäre Dateien und Job-spezifische Zugangsdaten bereinigt. Der Self-hosted Runner darf keine ungesicherten Pull-Request-Jobs auf demselben System ausführen.

Vergleichen Sie drei Betriebsmodelle:

  • Dauerhaft gemeinsam genutzter Mac: Niedrige Änderungsfrequenz, aber höheres Risiko durch persistente Arbeitsverzeichnisse, installierte Werkzeuge und vergessene Zugangsdaten.
  • Kurzlebiger Runner: Weniger Rückstände zwischen Jobs, aber zusätzlicher Aufwand für Registrierung, Deprovisionierung und Wiederanbindung.
  • Dedizierter Release-Mac: Klare Trennung und bessere Nachvollziehbarkeit, aber zusätzliche Kosten und Kapazitätsplanung.

Für ein Remote-Mac-Konzept sollten Sie nicht nur die Rechenleistung bewerten. Prüfen Sie auch Zugriffskanal, Root-Rechte, Runner-Routing, Keychain-Isolation, Neustartverhalten und Datenlöschung. Eine Übersicht zu Remote-Mac-Angeboten und verfügbaren Mietmodellen kann als Ausgangspunkt für einen isolierten technischen Versuch dienen. Preis- oder Kapazitätsannahmen sollten Sie erst nach einer konkreten Konfiguration treffen; veröffentlichte Hardwaredaten ersetzen keine Sicherheitsabnahme.

Erfahrung aus der Betriebsplanung: Ein gemeinsam genutzter Mac ist für einen Build-Test nicht automatisch ein geeigneter Release-Knoten. Wenn derselbe Host sowohl unbekannte Pull-Request-Jobs als auch Apple-Signierung verarbeitet, kann eine erfolgreiche OIDC-Reparatur die wichtigere Sicherheitsgrenze verdecken.

06

Audit und Wiederanlauf entscheiden über die Freigabe

Nach der Policy-Änderung brauchen Sie einen positiven und einen negativen Nachweis. Ein erfolgreicher Login allein zeigt nur, dass mindestens eine Identität akzeptiert wurde. Er zeigt nicht, ob ein fremdes Repository, ein falscher Branch oder ein nicht freigegebenes Environment ebenfalls zugelassen wird.

Führen Sie diese Prüfungen in einem festen Testlauf durch:

  1. Erlaubter Branch mit erlaubtem Environment erhält den vorgesehenen kurzlebigen Cloud-Token.
  2. Nicht erlaubter Branch wird abgewiesen.
  3. Nicht erlaubtes Environment wird abgewiesen.
  4. Nicht autorisiertes Repository erhält keine Cloud-Rolle.
  5. Wiederverwendbarer Workflow wird mit seinem tatsächlichen Identitätskontext geprüft.
  6. Pull Request aus einer nicht vertrauenswürdigen Quelle erhält weder Produktionsrolle noch Signatur-Keychain.
  7. Ein absichtlich ungültiger sub-Wert wird abgelehnt.
  8. Das Ergebnis wird mit Workflow-ID, Policy-Version und Zeitpunkt protokolliert.

Bewahren Sie die alte und neue Vertrauensstrategie, den redigierten Token, die Testfälle sowie die Rückfallbedingung auf. Kontonamen, Rollenkennungen, interne URLs und Tokenwerte müssen in der weitergegebenen Dokumentation anonymisiert werden.

Wenn ein produktiver Build auf einem Self-hosted Runner läuft, gehören zusätzlich diese Punkte in die Abnahme:

  • Runner nach der Policy-Änderung kontrolliert neu starten.
  • Prüfen, ob der Auftrag wieder an den vorgesehenen Runner geroutet wird.
  • Workspace und temporäre Dateien nach einem erfolgreichen und einem abgebrochenen Job kontrollieren.
  • Keychain-Zugriff nur im signierenden Job testen.
  • Einen Ausfall des primären Knotens simulieren.
  • Einen Ersatzknoten nur dann freigeben, wenn seine Identität und Signaturgrenzen dokumentiert sind.

Die offizielle GitHub-OIDC-Referenz sollte bei jeder späteren Änderung erneut geprüft werden. GitHub kann Standardformate, Produktumfang oder Enterprise-Server-Unterstützung ändern. Am 11.09.2026 gilt für diesen Leitfaden die oben beschriebene Abgrenzung; sie ist keine dauerhafte Zusage für spätere Produktversionen.

07

Die Entscheidung zwischen Cloud-Job und Mac-Release-Knoten

Nutzen Sie OIDC für den Teil, den der unterstützte Cloud-Dienst tatsächlich föderiert. Halten Sie Apple-Signaturmaterial auf einer enger kontrollierten Mac-Umgebung. Für den technischen Versuch kann ein Remote-Mac die Trennung aus Build, Cloud-Zugriff und Signierung sichtbar machen. Die passende Mac-Konfiguration hängt jedoch von Xcode-Version, Artefaktgröße, Parallelität, Runner-Registrierung und Organisationsrichtlinie ab.

Wenn Ihr bestehender Knoten alle Aufgaben gemeinsam ausführt, ist ein schrittweiser Umbau sinnvoll:

  1. Cloud-Authentifizierung auf einen nicht signierenden Build-Job begrenzen.
  2. Artefakte signiert an einen separaten Release-Job übergeben.
  3. Release-Job auf einen dedizierten oder besonders gehärteten Mac routen.
  4. Keychain-Zugriff und App-Store-Connect-Zugriff getrennt protokollieren.
  5. Erst nach negativen Tests die Produktionsfreigabe aktivieren.

Für die Planung können Sie Mac-Mietpreise und Laufzeitmodelle als Beschaffungspunkt prüfen. Entscheidend ist aber nicht der niedrigste Mietpreis, sondern ob der Knoten Ihre Identitätsgrenzen, Wiederanlaufanforderungen und Audit-Nachweise erfüllt.

Option Cloud-OIDC Apple-Signierung Residualrisiko Geeignet, wenn
Bestehender gemeinsamer Mac Im selben Job möglich Im selben Host möglich Hohe Vermischung von Rollen und Arbeitsdaten Nur für kontrollierte Tests ohne Produktionsschlüssel
Getrennter Build- und Release-Runner Build-Runner erhält kurzlebigen Cloud-Zugriff Release-Runner besitzt Signaturmaterial Mittlere Komplexität, klare Übergabe nötig Teams Cloud-Zugriff und Signierung schrittweise trennen
Dedizierter Remote-Mac für Release Cloud-Zugriff nur nach Freigabe Keychain auf isoliertem Knoten Höhere Betriebs- und Abnahmeanforderungen Produktionssignierung dauerhaft kontrolliert werden muss
Langfristiger Cloud-Schlüssel als Rückfall Umgeht OIDC-Fehler Keine Apple-Signierung ersetzt Hohe Schlüssel- und Rotationslast Nur als streng befristete Notmaßnahme mit dokumentiertem Rückbau

Die Vergleichstabelle ersetzt keine Sicherheitsprüfung. Für jede Option müssen Sie erlaubte Subjekte, abgelehnte Subjekte, Token-Gültigkeit, Environment-Freigabe und Signaturzugriff nachweisen. Besonders der letzte Ansatz sollte nicht zur Standardlösung werden: Er behebt keine Claim-Abweichung, sondern verschiebt das Risiko in ein langlebiges Geheimnis.

Wenn Sie nach der OIDC-Reparatur feststellen, dass Cloud-Identität, Runner-Ausführung und Apple-Signierung weiterhin auf demselben gemeinsam genutzten Host liegen, ist ein isolierter Remote-Mac-Pilot der nächste sinnvolle Schritt. So können Sie Routing, Neustart, Workspace-Bereinigung und Keychain-Trennung testen, ohne sofort die gesamte CI/CD-Architektur umzubauen.

Der bestehende Ansatz hat typischerweise drei Schwächen: gemeinsame Hosts hinterlassen dauerhafte Arbeitsdaten, langfristige Cloud-Schlüssel erhöhen Rotations- und Leckrisiken, und eine vermischte Signierungsumgebung erschwert die forensische Prüfung. Eine gemietete Mac-Umgebung von VpsMesh kann für einen zeitlich begrenzten Validierungsknoten die bessere Option sein, wenn Sie keine eigene Hardware bereitstellen möchten. Für dauerhaft hohe Last, spezielle physische Schnittstellen oder streng lokale Datenhaltung bleibt der Kauf und Betrieb eigener Macs die ehrlichere Alternative.

Beginnen Sie daher mit einem kontrollierten Token, nicht mit einer Policy-Wildcard. Aktualisieren Sie die Vertrauensregel nur anhand der beobachteten Claims und geben Sie den Mac-Releasepfad erst frei, wenn Cloud-Zugriff und Apple-Signatur nachweisbar getrennt sind.