Sperren von Abhängigkeiten von Actions in den Workflows eines Repositorys

Generieren Sie eine Sperrdatei, die jede von Ihren Workflows verwendete Aktion auf einen verifizierten Commit festlegt, und halten Sie sie auf dem Laufenden, wenn sich Ihre Abhängigkeiten ändern.

Wer kann dieses Feature verwenden?

People with write access to a repository

GitHub Enterprise Cloud

In diesem Artikel

Durch das Sperren der Abhängigkeiten Ihrer Workflows wird sichergestellt, dass die von Ihnen referenzierten Aktionen denselben Code enthalten, der ursprünglich überprüft wurde. Weitere Informationen findest du unter Sperrdateien für Workflow-Abhängigkeiten.

1. Überprüfen Sie Ihre Aktionsreferenzen

Durch das Erstellen einer Sperrdatei werden die Abhängigkeiten auf Commits basierend auf dem aktuellen Branch- oder Tag-Verweis fixiert. Stellen Sie sicher, dass dies die Versionen sind, die Sie fixieren möchten.

Überprüfen Sie, ob jeder uses Verweis in Ihren Workflows auf eine unterstützte, aktuelle Version der Aktion verweist. Bewährte Methoden finden Sie unter Referenz zur sicheren Verwendung.

Wenn eines Ihrer Workflows einen wiederverwendbaren Workflow in einem anderen Repository aufruft, überprüfen Sie diese Verweise ebenfalls. Die Abhängigkeiten eines wiederverwendbaren Workflows werden von der Sperrdatei des Repositorys abgedeckt, in dem er definiert ist, nicht durch Ihre Sperrdatei. Dieses Quell-Repository benötigt eine eigene Sperrdatei für die vollständige Abdeckung. Wenn Ihre Organisation freigegebene Workflows verwaltet, nehmen Sie diese Repositorys zuerst auf. Siehe Wiederverwenden von Workflowkonfigurationen.

Wir empfehlen, Dependabot Ihre GitHub Actions-Abhängigkeiten verwalten zu lassen. Wenn dies noch nicht aktiviert ist, aktivieren Sie dies, bevor Sie die Sperrdatei erstellen. Siehe Deine Aktionen mit Dependabot auf dem neuesten Stand halten.

2. Installieren Sie die actions-lock Erweiterung

  1. Installieren Sie das GitHub CLI.

  2. Installieren Sie die Erweiterung.

    Bash
    gh extension install github/gh-actions-lock

Tipp

Um die Erweiterung später zu aktualisieren, führen Sie gh extension upgrade gh-actions-lock aus.

3. Sperrdatei generieren

Führen Sie aus dem Stammverzeichnis Ihres Repositorys die Erweiterung ohne Argumente aus. Es scannt jeden Workflow unter .github/workflows/, pinnt jede auflösbare Aktion an eine Commit-SHA und schreibt die Sperrdatei.

Bash
gh actions-lock

Um einen einzelnen Workflow anstelle des gesamten Verzeichnisses zu onboarden, übergeben Sie den Pfad.

Bash
gh actions-lock .github/workflows/ci.yml

Die Erweiterung folgt nie oder fixiert eine lokale Pfadaktion (uses: ./…). Bei einem ./-Pfad wird das ausgeführt, was im Arbeitsbereich des Runners ausgecheckt ist, sodass die Erweiterung sie nicht anheften kann und nicht sehen kann, was verwendet wird. Ein $/-Pfad führt die repositoryeigene Aktion Ihres Repositorys beim Commit des Workflows aus, sodass sie fixiert ist und die von ihr verwendeten Aktionen fixiert werden können. Einen Vergleich der beiden finden Sie unter Workflowsyntax für GitHub Actions.

Wenn eine lokale Aktion in Ihrem Checkout andere Aktionen verwendet, meldet die Erweiterung einen local-action-Fehler und schreibt nichts, da diese Aktionen zur Laufzeit ohne Lockfile-Einträge fehlschlagen würden. Führen Sie Folgendes aus, um die lokale Aktion als Verweis auf dasselbe Repository zu sperren:

Bash
gh actions-lock --migrate-local-actions

Um den ./ Verweis beizubehalten und ihn stattdessen als Warnung zu melden, übergeben Sie --ignore-local-actions. Siehe Beibehalten einer lokalen Pfadaktion.

Führen Sie gh actions-lock --help aus, um die vollständige Liste aller Optionen anzuzeigen. Hilfe zu einem bestimmten Fehler oder einer bestimmten Warnung finden Sie im Handbuch zur Problembehandlung bei gh-actions-lock.

Beibehalten einer lokalen Pfadaktion

Wenn Sie --ignore-local-actions übergeben, hängt das, was zur Laufzeit geschieht, von den Aktionen ab, die von der lokalen Aktion verwendet werden:

  • Es verwendet keine anderen Aktionen, beispielsweise nur run: Schritte: Der Workflow wird normal ausgeführt.
  • Sie verwendet Aktionen mit Sperrdateieinträgen für denselben Workflow: Der Workflow wird normal ausgeführt.
  • Es verwendet eine Aktion, die keinen Lockfile-Eintrag für diesen Workflow enthält: Der Job schlägt fehl, wenn er den Schritt der lokalen Aktion erreicht, mit einem Fehler wie lockfile missing pin for octo-org/setup-tool@v2.0.0z. B. . Frühere Schritte wurden bereits ausgeführt.

Stattdessen empfehlen wir --migrate-local-actions, sodass die Aktion als angeheftete $/-Referenz ausgeführt wird. Wenn Sie den ./ Verweis beibehalten müssen, geben Sie die Workflow-Sperrdateieinträge für die Aktionen an, die von der lokalen Aktion verwendet werden. Fügen Sie eine zusammengesetzte Aktion hinzu, die dieselben Aktionen mit denselben Verweisen verwendet, und rufen Sie sie aus dem Workflow in einem Schritt auf, der nie ausgeführt wird. Führen Sie dann gh actions-lock --ignore-local-actions aus.

# .github/actions/lock-local-deps/action.yml
name: Lock local action dependencies
description: Never runs. Lists the actions that ./.github/actions/build uses.
runs:
  using: composite
  steps:
    - uses: octo-org/setup-tool@v2.0.0

# In the workflow
steps:
  - uses: actions/checkout@v6
  - if: false
    uses: $/.github/actions/lock-local-deps
  - uses: ./.github/actions/build

Die Einträge müssen für denselben Workflow aufgezeichnet werden. Ein Eintrag, der nur für einen anderen Workflow aufgezeichnet wird, zählt nicht. Wenn sich die Abhängigkeiten der lokalen Aktion ändern, aktualisieren Sie die zusammengesetzte Aktion und führen Sie gh actions-lock --ignore-local-actions erneut aus.

4. Überprüfen Sie die Änderungen und führen Sie den Commit aus.

Die Erweiterung ändert mehr als nur die Sperrdatei. Überprüfen Sie daher den vollständigen Diff, bevor Sie einen Commit ausführen. Außerdem werden Ihre Workflowverweise uses auf die aufgelöste spezifische Version umgeschrieben, sodass ein Verweis wie z. B. octo-org/deploy-action@v3 zu octo-org/deploy-action@v3.1.0 werden kann. Dadurch wird der Verweis genauer, ohne den Commit zu ändern, zu dem er aufgelöst wird.

Wichtig

Wenn Ihr Repository, Ihre Organisation oder Ihr Unternehmen nur bestimmte Aktionen zulässt, überprüfen Sie die Allowlist, bevor Sie einen Commit ausführen. Nachdem ein Workflow eingebunden wurde, wird die Erlaubnisliste anhand gesperrter Commit-SHAs anstelle von Tags überprüft, da ein Tag auf anderen Code verschoben werden kann, eine gesperrte SHA jedoch nicht verschoben werden kann. Einträge, die an ein Tag angeheftet sind, wie actions/checkout@v6, stimmen nicht mehr überein, sobald ein Workflow integriert ist. Verwenden Sie stattdessen einen Platzhalter oder den vollständigen Commit-SHA. Siehe Einstellung der GitHub Actions für ein Repository verwalten.

Wenn Sie --migrate-local-actions übergeben haben, schreibt die Erweiterung auch Verweise auf Aktionen in Ihrem eigenen Repository von uses: ./… zu uses: $/… in Ihren Workflows und den action.yml-Dateien Ihres Repositorys um. Dies geschieht nur, wenn Sie die Option übergeben, da sich die beiden Formen unterschiedlich verhalten. Ein ./-Pfad wird relativ zu dem aufgelöst, was sich im Arbeitsbereich des Runners befindet, während ein $/…-Verweis immer im eigenen Commit des Workflows ausgeführt wird, sodass kein Sperrdateieintrag erforderlich ist. Überprüfen Sie jede neu geschriebene Zeile.

5. Halten Sie die Sperrdatei auf dem aktuellen Stand

Halten Sie die Sperrdatei mit den Workflowdateien und Sicherheitsupdates Ihres Repositorys auf dem neuesten Stand.

  1. Führen Sie die Erweiterung erneut aus, wenn Sie Abhängigkeiten ändern. Führen Sie gh actions-lock erneut aus, wenn Sie einen Workflow mit usesAbhängigkeiten hinzufügen oder usesAbhängigkeiten in einem vorhandenen Workflow hinzufügen oder entfernen.

  2. Lassen Sie Dependabot Versionssprünge handhaben. Wenn Dependabot ein Versionsupdate für eine Aktion in einem Workflow öffnet, den Sie integriert haben, wird auch der entsprechende Lockfile-Eintrag im selben Pull Request neu generiert. Ihre Workflowdatei und Die Sperrdatei können nicht auseinanderdriften.

Dependabot aktualisiert nur Sperrdateieinträge für Workflows, die bereits aufgenommen sind. Wenn eine Aktion in einem Workflow aktualisiert wird, die sich nicht in der Sperrdatei befindet, wird die Workflowdatei wie gewohnt aktualisiert, während die Sperrdatei unverändert bleibt.

  1. Lösen Sie Verweise erneut auf, die verschoben wurden. Wie die Erweiterung einen verschobenen Verweis behandelt, hängt vom Verweis ab:

    • Eine Verzweigung oder teilweise Version, z. B. main oder v3, behält den gesperrten Commit bei, und die Erweiterung meldet eine ref-moved-Warnung. Um ihn fortzusetzen, überprüfen Sie den Upstreamverlauf, und führen Sie dann aus gh actions-lock --relock.
    • Ein vollständiges Versions-Tag, z. B. v3.1.0, muss auf den gesperrten Commit verweisen. Wenn das Tag verschoben wurde, meldet die Erweiterung einen Fehler, bis Sie uses: ausführen oder die gh actions-lock --relock-Zeile ändern.
    • Ein umgeschriebener Verlauf, bei dem sich der gesperrte Commit nicht mehr im Verlauf des Verweises befindet, z. B. nach einem Force-Push, ist ein Fehler, den --relock nicht behebt. Nachdem Sie den upstream-Verlauf überprüft haben, führen Sie gh actions-lock --accept-moved aus. Verwenden Sie --accept-moved nicht in der Automatisierung.

Überprüfen von Sperrdateiänderungen

Überprüfen Sie Änderungen an der Sperrdatei wie jede andere Abhängigkeitsänderung:

  • Eine geänderte commit ist der Code, der in Ihren Workflows ausgeführt wird. Behandeln Sie es wie jede andere Aktualisierung einer Abhängigkeit.
  • Ein geändertes owner_id oder repo_id sollte selten sein. Dies bedeutet, dass das Repository hinter diesem Namen nicht das Repository ist, das Sie ursprünglich fixiert haben. Untersuchen Sie dies daher, bevor Sie die Zusammenführung durchführen.

Wenn eine Sperrdatei falsch aussieht, beheben Sie Ihre Workflowdateien und generieren Sie die Sperrdatei neu. Bearbeiten Sie die Sperrdatei nie manuell.

Nächste Schritte

Nachdem Sie eine Sperrdatei für ein Repository generiert haben, stellen Sie sicher, dass ihre Verwendung durchgesetzt wird und sie aktuell bleibt, ohne dass Entwickler daran denken müssen, Befehle auszuführen. Siehe Erzwingen von Lockfiles für Abhängigkeiten von Aktionen.