CI ohne Überraschung: GitHub Actions bekommen ein Lockfile

Ein grüner Workflow kann morgen anderen Code ausführen

In vielen Repositories sieht eine Action-Abhängigkeit harmlos aus: uses: actions/checkout@v4. Das ist lesbar, verbreitet und bequem. Der Haken steckt hinter @v4. Ein Tag oder Branch kann sich bewegen. Damit kann derselbe unveränderte Workflow bei einem späteren Lauf auf einem anderen Commit landen als der Code, den das Team ursprünglich geprüft hat.

Am 14. Oktober 2026 hat GitHub deshalb Workflow Dependency Lockfiles als Public Preview veröffentlicht. Die Idee kennen Entwickler von npm, pnpm oder Cargo: Die deklarierte, gut lesbare Version bleibt im Workflow stehen, während eine maschinell gepflegte Datei den tatsächlich ausgeführten Commit festhält.

Das löst nicht jedes Supply-Chain-Problem. Es schließt aber eine unangenehme Lücke zwischen „Diese Referenz haben wir gelesen“ und „Diesen Code hat der Runner wirklich ausgeführt“.

Was genau wird gesperrt?

Das neue Lockfile liegt unter .github/workflows/actions.lock. Es wird von der GitHub-CLI-Erweiterung gh-actions-lock erzeugt und sollte nicht von Hand bearbeitet werden.

Für jeden aufgenommenen Workflow enthält es zwei Arten von Information:

• welche Actions und wiederverwendbaren Workflows der Workflow verwendet;
• auf welchen exakten Commit jede Referenz beim Sperren gezeigt hat;
• die numerische Identität von Repository und Owner;
• auch transitive Action-Abhängigkeiten, also Actions, die von einer anderen Action nachgeladen werden.

Beim Lauf verwendet GitHub den gesperrten Commit. Ein verschobener Tag ändert damit nicht still die ausgeführte Version. Die gespeicherte Repository-Identität erschwert zusätzlich Angriffe, bei denen ein Name nach Transfer oder Umbenennung von einem anderen Repository übernommen wird.

Eine wichtige Grenze: Abhängigkeiten innerhalb eines aufgerufenen wiederverwendbaren Workflows werden von dessen eigenem Repository-Lockfile abgedeckt. Das aufrufende Repository sperrt den wiederverwendbaren Workflow selbst, aber nicht automatisch dessen gesamte interne Welt.

Warum das besser ist als nur ein SHA im YAML

GitHub hat lange empfohlen, Drittanbieter-Actions direkt auf einen vollständigen Commit-SHA zu pinnen. Das bleibt ein solider Ansatz. Ein Lockfile verbessert aber drei praktische Punkte:

1. Der Workflow bleibt mit @v4 oder @v4.2.1 für Menschen lesbar.
2. Transitive Action-Abhängigkeiten werden ebenfalls erfasst.
3. Die Repository-Identität wird neben dem Commit gespeichert.

Damit trennt sich die Absicht von der Ausführung: Im YAML steht die gewünschte Version, im Lockfile der geprüfte Snapshot. Ein Update kann beide Ebenen gemeinsam ändern und im Pull Request sichtbar machen.

Der Einstieg dauert keine Plattformmigration

Die Erweiterung wird über die GitHub CLI installiert:

gh extension install github/gh-actions-lock

Danach erzeugt gh actions-lock das Lockfile und nimmt Workflows auf. Teams müssen nicht sofort alle Pipelines umstellen. GitHub unterstützt ein schrittweises Onboarding pro Workflow. Sobald ein Workflow aufgenommen ist, müssen seine Abhängigkeiten vollständig im Lockfile stehen.

Ein vernünftiger Start sieht so aus:

1. Mit einem nicht kritischen CI-Workflow beginnen.
2. Erzeugte Änderungen und aufgelöste Commits wirklich prüfen.
3. Lockfile und Workflow-Anpassungen gemeinsam committen.
4. gh actions-lock --verify als eigenen CI-Check hinzufügen.
5. Erst danach Deployments und Release-Pipelines aufnehmen.

--verify prüft ohne Dateiveränderung, ob alle Einträge vorhanden und weiterhin vertrauenswürdig auflösbar sind. --verify-local arbeitet offline, kontrolliert aber nur die Vollständigkeit. Für das Schutzgitter in CI ist deshalb die Online-Prüfung die relevante Variante.

Updates werden bewusst, nicht dauerhaft eingefroren

Ein Lockfile darf nicht zu einem Museum werden. Wird eine Action aktualisiert, muss der neue Commit geprüft und anschließend gesperrt werden.

Für normale Änderungen an einem Workflow wird gh actions-lock erneut ausgeführt. Bereits gesperrte Referenzen bleiben dabei stabil. Sollen bewegliche Tags oder Branches bewusst auf ihren aktuellen Stand gebracht werden, erzeugt gh actions-lock --relock neue Auflösungen.

Die Option --accept-moved verdient besondere Vorsicht: Sie akzeptiert auch Referenzen, deren bisheriger Commit nicht mehr im erwarteten Upstream erreichbar ist. Genau dieser Zustand kann auf einen legitimen Umbau, aber auch auf einen problematischen Eingriff hindeuten. Er gehört in ein menschliches Review und nicht in einen automatischen Nachtjob.

Dependabot reduziert die Wartungsarbeit. Aktualisiert es eine Action in einem bereits aufgenommenen Workflow, regeneriert es laut GitHub den passenden Lockfile-Eintrag im selben Pull Request. So lassen sich Versionsreferenz, Commit und Tests zusammen prüfen.

Das Lockfile ist eine Kontrolle, kein Gütesiegel

Ein exakt gesperrter Commit kann trotzdem unsicher sein. Locking beantwortet die Frage „Läuft derselbe Code?“, nicht „Ist dieser Code gutartig?“.

Vor dem ersten Sperren bleibt deshalb ein Abhängigkeitsreview nötig:

• Wer pflegt die Action und wie aktiv ist das Projekt?
• Welche Berechtigungen erhält der Job?
• Welche Secrets sind im Schritt erreichbar?
• Läuft fremder Code vor oder nach dem Checkout eigener Quellen?
• Ist die Action wirklich notwendig oder reichen wenige Shell-Zeilen aus dem eigenen Repository?
• Gibt es eine nachvollziehbare Release-Historie und Security Policy?

Besonders gefährlich sind überbreite permissions, schreibende Standard-Tokens und Secrets auf Workflows, die durch nicht vertrauenswürdige Eingaben ausgelöst werden. Ein Lockfile reduziert Abhängigkeitsdrift, aber nicht den Blast Radius eines falsch entworfenen Workflows.

Ein praktischer Review für den ersten Pull Request

Der erste Lockfile-PR sollte nicht einfach wegen „generated file“ durchgewunken werden. Wir prüfen ihn in vier Schichten.

Workflow-Inventar: Sind nur die erwarteten Workflows aufgenommen? Wurden lokale Actions korrekt erkannt? Die Preview hat laut Repository-Dokumentation noch Einschränkungen bei lokalen Pfad-Actions; solche Hinweise dürfen nicht überlesen werden.

Abhängigkeitsgraph: Tauchen überraschende transitive Actions auf? Ein kleiner Marketplace-Schritt kann intern weitere Bausteine laden. Das neue Inventar macht diese Kette erstmals bequem reviewbar.

Berechtigungen: Passt jede Action zu den Token-Rechten des Jobs? Locking rechtfertigt keine Schreibrechte.

Betrieb: Läuft die Pipeline nach dem Sperren auf Pull Request, Hauptbranch und geplantem Trigger? Reproduzierbarkeit ist wertlos, wenn ein seltener Release-Pfad erst Wochen später bricht.

Policies erst nach einem Pilot erzwingen

GitHub bietet zusätzlich eine Require lockfile-Policy als Public Preview für Enterprise-, Organisations- und Repository-Administratoren an. Sie kann dafür sorgen, dass Workflows nicht außerhalb des neuen Modells laufen.

Die Versuchung ist groß, die Policy sofort organisationsweit zu aktivieren. Besser ist ein gestufter Rollout:

1. zwei bis drei typische Repositories auswählen;
2. Sonderfälle wie Reusable Workflows und lokale Actions dokumentieren;
3. Update- und Incident-Prozess erproben;
4. zentrale CI-Checks und Dependabot konfigurieren;
5. erst dann die Policy auf weitere Teams ausrollen.

Die Funktion ist ausdrücklich Public Preview. Format, Flags und Verhalten können sich noch ändern; GitHub Enterprise Server wird von der CLI-Erweiterung derzeit nicht unterstützt. Ein Pilot verhindert, dass eine gut gemeinte Sicherheitsregel plötzlich sämtliche Releases blockiert.

Was wir ab jetzt bei neuen Projekten tun würden

Für neue GitHub-Actions-Projekte ergibt sich ein klarer Standard:

• möglichst wenige externe Actions verwenden;
• Job-Berechtigungen explizit und minimal setzen;
• kritische Workflows in das Lockfile aufnehmen;
• gh actions-lock --verify als Pflichtcheck ausführen;
• Updates nur über reviewbare Pull Requests einspielen;
• Lockfile, Workflow und Testergebnis gemeinsam bewerten;
• Preview-Änderungen der Funktion beobachten.

Bei bestehenden Projekten priorisieren wir Pipelines, die deployen, signieren, veröffentlichen oder Produktions-Secrets sehen. Dort ist der Unterschied zwischen einer lesbaren Versionsreferenz und einem überprüfbaren Commit am wertvollsten.

Der eigentliche Gewinn ist nicht die zusätzliche Datei. Es ist eine klarere Vereinbarung im Team: CI-Abhängigkeiten sind Produktionscode. Sie bekommen Inventar, Review, reproduzierbare Auflösung und einen kontrollierten Update-Weg — genau wie die Anwendung, die sie ausliefert.

Quellen

• GitHub Changelog: Workflow dependency lockfiles in public preview
• GitHub Docs: Workflow dependency lockfiles
• GitHub: gh-actions-lock CLI extension
• GitHub Docs: Dependabot version updates for Actions