GitHub-Actions-Lockfile fixiert Action-Code, aber nicht die gesamte CI

Kann man GitHub Actions vertrauen, wenn ein Workflow eine Action über einen Tag wie @v3 einbindet? Das Lockfile legt fest, welcher Commit der Action ausgeführt wird – selbst wenn der Tag später verschoben wird. Teams können Abhängigkeitsupdates im Diff prüfen und eine nachvollziehbare Liste der in der CI verwendeten Actions führen. Die praktische Grenze: Das Lockfile erfasst Actions, die in Schritten aufgerufen werden; ein auf Job-Ebene eingebundener Reusable Workflow muss separat festgeschrieben werden. Der beschriebene Mechanismus ist in GitHub Enterprise Cloud verfügbar.

Was genau pinnt das Lockfile?

Verweise auf Branches und Tags sind praktisch, doch die Version, auf die sie zeigen, kann sich ändern. Ein Eintrag wie uses: octo-org/deploy-action@v3 verweist auf einen Tagnamen; GitHub löst diesen Verweis beim Ausführen in einen Commit auf. Verschiebt der Projektinhaber den Tag, kann ein späterer Lauf ohne festgeschriebene Abhängigkeit anderen Code erhalten.

Laut der GitHub-Dokumentation zu Lockfiles speichert die Datei .github/workflows/actions.lock Abhängigkeitsverweise und die entsprechenden Commit-SHAs, einschließlich transitiver Abhängigkeiten – also Actions, die von anderen Actions verwendet werden. Die Datei wird durch die GitHub-CLI-Erweiterung gh actions-lock erstellt und nicht manuell bearbeitet.

Der Generator kann außerdem uses-Verweise in Workflow-Dateien präzisieren: Beispielsweise kann er einen Verweis auf einen veränderlichen Tag konkretisieren und dabei den Commit beibehalten, auf den der Verweis bei der Erstellung des Lockfiles aufgelöst wurde. Bei der Einführung sollte deshalb das gesamte Diff geprüft werden – Änderungen an Workflows und Lockfile – und sichergestellt werden, dass die festgeschriebene Version derjenigen entspricht, die das Team ausführen möchte.

Danach wird ein Abhängigkeitsupdate zu einer sichtbaren Änderung im Repository: Das Team kann die Commit-Änderung prüfen, besprechen und im regulären Review freigeben. Das Lockfile hilft dabei, Action-Code zu auditieren und Abhängigkeiten konsistent zu halten; es bestätigt für sich genommen nicht, dass der ausgewählte Code sicher ist.

Wo endet der Geltungsbereich?

Ein Reusable Workflow, der über jobs.<job_id>.uses aufgerufen wird, ist nicht durch das Lockfile des aufrufenden Repositorys erfasst. Die Abhängigkeiten eines Reusable Workflows gehören zu dem Repository, in dem der Workflow definiert ist. Um den Aufruf selbst festzuschreiben, geben Sie die vollständige Commit-SHA an; um seine Actions im Ursprungsrepository zu pinnen, ist dort ein eigenes Lockfile erforderlich.

Das Lockfile kontrolliert den Action-Code, aber nicht andere Build-Eingaben, etwa an eine Action übergebene Parameter, Secrets oder das Runner-Image. Es beantwortet eine konkrete Frage: Welcher Commit des Action-Codes wird ausgeführt? Für diese anderen Elemente sind eigene Kontrollregeln nötig.

Ein Sonderfall ist eine lokale Action, die über einen Pfad wie uses: ./ aufgerufen wird. Laut GitHub-Anleitung pinnt oder analysiert die Erweiterung gh actions-lock lokale Action-Pfade nicht. Verwendet eine solche Action weitere Actions, müssen deren Abhängigkeiten separat verwaltet werden; die Dokumentation beschreibt die Möglichkeit, Verweise auf lokale Actions in das Format $/ zu migrieren.

Ein Lockfile-Eintrag kann also Teil einer Abhängigkeitskette sein, ersetzt aber nicht die Kontrolle aller ihrer Glieder. Bei einem externen Reusable Workflow sollten Sie den festgeschriebenen Aufruf und den Zustand des Ursprungsrepositorys prüfen; bei lokalen Actions sollten Sie kontrollieren, wie deren Abhängigkeiten erfasst werden.

Wie lässt sich die Kontrolle einführen, ohne die CI unerwartet zu stoppen?

GitHub empfiehlt zunächst einen Pilotversuch mit ausgewählten Repositorys und Workflows. Die Richtlinie „Require lockfile“ blockiert die Ausführung der betroffenen Workflows, wenn kein gültiges Lockfile vorhanden ist – auch bei Workflows ohne uses:-Abhängigkeiten. Der Modus „Evaluate“ für Richtlinien ist nur in GitHub Enterprise Cloud verfügbar. Bereiten Sie daher zunächst den Geltungsbereich und automatische Updates vor und aktivieren Sie anschließend die verpflichtende Regel.

1. Prüfen Sie die Ausgangsverweise. Vergewissern Sie sich vor dem Erstellen des Lockfiles, dass die Actions auf Versionen verweisen, die das Team tatsächlich pinnen möchte. Der Generator pinnt den Commit, der sich aus dem aktuellen Verweis ergibt.
2. Erstellen und prüfen Sie das Lockfile. Installieren Sie die Erweiterung gh-actions-lock, führen Sie gh actions-lock im Stammverzeichnis des Repositorys aus und prüfen Sie das vollständige Diff, einschließlich geänderter uses-Verweise.
3. Richten Sie Aktualisierungen und Prüfungen ein. Dependabot kann passende Einträge für bereits eingebundene Workflows aktualisieren. In der CI lässt sich für Pull Requests eine Prüfaufgabe mit gh actions-lock --verify einrichten, um ein veraltetes Lockfile vor dem Haupt-Build zu erkennen.
4. Benennen Sie Reviewer. Nehmen Sie .github/workflows/actions.lock in CODEOWNERS auf und verlangen Sie, dass für Änderungen die für die Build-Sicherheit Verantwortlichen als Reviewer hinzugezogen werden.
5. Führen Sie einen Richtlinien-Pilotversuch durch. Beginnen Sie mit den eingebundenen Repositorys und Workflows. Analysieren Sie die Ergebnisse im Modus „Evaluate“ und vergewissern Sie sich vor dem Wechsel in den Modus „Active“, dass alle betroffenen Workflows vorbereitet sind und die Lockfiles aktuell bleiben.

„Require lockfile“ und die separate Richtlinie „Require actions to be pinned to a full-length commit SHA“ sind unterschiedliche Regeln; laut GitHub können sie gleichzeitig gelten. Auch CI-Prüfung und verpflichtende Richtlinie erfüllen unterschiedliche Aufgaben: Die erste erkennt bei der Arbeit an einem Pull Request veraltete Dateien, die zweite blockiert die Ausführung von Workflows, die die Vorgabe nicht erfüllen.

Beispiel: Deployment-Action aktualisieren

Angenommen, ein Workflow veröffentlicht eine Anwendung über octo-org/deploy-action@v3. Zunächst prüft das Team, auf welche Version dieser Verweis aufgelöst wird. Anschließend führt es gh actions-lock aus und prüft das Diff der Workflow-Datei zusammen mit dem Commit-Eintrag im Lockfile. Bei einem Action-Update sieht der Reviewer die Änderungen an den Verweisen und am festgeschriebenen Commit. So lässt sich das konkrete Update beurteilen, statt darauf zu vertrauen, dass ein veränderlicher Tag immer auf denselben Code zeigt.

Wird das Deployment durch einen Reusable Workflow aus einem anderen Repository ausgeführt, erfasst das lokale Lockfile dessen Abhängigkeiten nicht. Pinnen Sie den Verweis auf den Reusable Workflow mit der vollständigen SHA und prüfen Sie, ob das Ursprungsrepository seine eigenen Action-Abhängigkeiten verwaltet. In großen Organisationen macht dies aus uneinheitlichen Regeln einen überprüfbaren Prozess, während Parameter, Secrets und Runner weiterhin separat kontrolliert werden.

Ein Lockfile ist eine nützliche Kontrollebene für Action-Code: Es macht Versionen und Updates nachvollziehbar, einschließlich transitiver Abhängigkeiten. Für eine zuverlässige Abdeckung sollten Sie außerdem Reusable Workflows und lokale Actions prüfen, Aktualisierungen automatisieren und die verpflichtende Richtlinie erst nach einem Pilotversuch einführen.