Sperrdateien für Workflow-Abhängigkeiten

Eine Sperrdatei legt jede Aktion, von der Ihre Workflows abhängig sind, auf einen überprüften Commit fest, sodass der von Ihnen überprüfte Code der ausgeführte Code ist.

In diesem Artikel

Warum Workflow-Abhängigkeiten sperren?

Workflows verweisen häufig über ein Tag oder einen Branch auf eine Aktion, z. B. uses: octo-org/deploy-action@v3 oder uses: octo-org/deploy-action@main. GitHub Actions löst diesen Verweis zur Laufzeit auf den Commit auf, auf den das Tag oder der Branch verweist.

Tags und Branches können verschoben werden. Daher ist nicht garantiert, dass der ausgeführte Code derselbe Code ist wie der Code, den der Workflowautor ursprünglich überprüft hat. Wenn das Konto eines vorgelagerten Betreuers kompromittiert und ein Tag neu zugewiesen wird, können Ihre Repositorys bösartigen Code ausführen.

Ein Lockfile für Workflow-Abhängigkeiten legt für jede Aktion, von der Ihre Workflows abhängig sind, einen Commit-SHA fest, einschließlich transitiver Abhängigkeiten. Aufrufe an wiederverwendbare Workflows (jobs.<job_id>.uses) werden nicht angeheftt. Wenn Sie einen wiederverwendbaren Workflow anheften möchten, verweisen Sie darauf mit dem vollständigen Commit-SHA. Ein Lockfile steuert, welcher Actions-Code auf dem Runner ausgeführt wird. Es steuert keine anderen Buildeingaben, z. B. Eingabeparameter, geheime Schlüssel oder das Runner-Image. Eine Lockdatei bietet Ihnen Folgendes für den behandelten Aktionscode:

  • Reproduzierbare Auflösung von Aktionsabhängigkeiten
  • Bearbeitbare Abhängigkeitsänderungen und Dependabot Versionsupdates
  • Ein auditierbares Inventar der Aktionsabhängigkeiten Ihrer CI/CD-Systeme

Wie funktioniert die Sperrdatei?

Die Sperrdatei wird in einem Repository unter dem Pfad .github/workflows/actions.lock definiert. Sie wird von einer GitHub CLIErweiterunggh actions-lock generiert und sollte niemals von Hand bearbeitet werden.

Sie können die Workflows eines Repositorys einzeln oder alle auf einmal für die Sperrdatei aktivieren. Nach dem Onboarding eines Workflows:

  • Jede Aktionsabhängigkeit, die der Workflow verwendet, muss in der Sperrdatei vorhanden sein.
  • Der gesperrte Commit wird ausgeführt, wenn der Workflow ausgeführt wird, und ist derjenige, der von Richtlinien für zulässige Aktionen überprüft wird.
  • Dieser Commit muss von dem Branch oder dem Tag aus erreichbar sein, die in der Sperrdatei im eigenen Repository der Aktion aufgezeichnet wurden. Ein Commit, der nur in einem Fork vorhanden ist oder nicht mehr von diesem Branch oder Tag aus erreichbar ist, wird abgelehnt, wenn der Workflow ausgeführt wird.

Eine Sperrdatei deckt die Workflows in ihrem eigenen Repository ab, einschließlich transitiver Abhängigkeiten (Aktionen, die Ihre Aktionsabhängigkeiten verwenden), mit Ausnahme von Abhängigkeiten wiederverwendbarer Workflowaufrufe. Wiederverwendbare Workflows können auch eigene Sperrdateien haben. Die Abhängigkeiten eines wiederverwendbaren Workflows werden durch die Sperrdatei des Repositorys festgelegt, in dem er definiert ist, nicht durch die Sperrdatei des Repositorys, das ihn aufruft.

Was enthält die Sperrdatei?

Die Lockfile verfügt über zwei Abschnitte. workflows zeichnet auf, welche Abhängigkeiten von jedem integrierten Workflow verwendet werden, und dependencies zeichnet auf, auf welchen Commit sich jeder dieser Verweise auflöst.

# This file is machine-generated by `gh actions-lock`.
# Do not edit by hand; run `gh actions-lock` to update.
# Docs: https://gh.io/actions-lockfile
version: 'v0.0.3'
workflows:
    '.github/workflows/ci.yml':
        - 'octo-org/deploy-action@v3.1.0'
dependencies:
    'octo-org/deploy-action@v3.1.0':
        ref: 'v3.1.0'
        commit: 'sha1-...'
        owner_id: 44036562
        repo_id: 197814629

Jeder Abhängigkeitsdatensatz:

  • ref: Das Tag oder die Verzweigung, von dem bzw. der der Commit stammt.
  • commit: Der genaue Commit, auf den der Verweis aufgelöst wurde. Dies ist der Code, der ausgeführt wird.
  • owner_id und repo_id: Die numerische Identität des Quell-Repositorys. GitHub Actions verwendet diese, um zur Laufzeit zu bestätigen, dass das Repository hinter dem Namen immer noch das von Ihnen fixierte ist.

Dieses strukturierte Format bietet Tools wie Dependabot einen maschinenlesbaren Datensatz, den sie zum Verwalten von Abhängigkeitsupdates verwenden können, ohne sich auf YAML-Kommentare als Versionsanmerkungen zu verlassen.

Wie lassen sich Lockfiles mit SHA-Pinning vergleichen?

GitHub hat in der Vergangenheit empfohlen, Aktionen von Drittanbietern in Ihren Workflowdateien auf einen vollständigen Commit-SHA festzulegen. Für Repositorys, die ein Lockfile verwenden, ist das ANheften von SHA in Workflowdateien nicht mehr erforderlich. Die Sperrdatei ist die bessere Option, da sie:

  • Unterstützt transitive Abhängigkeiten
  • Erleichtert das Lesen von Workflowdateien
  • Erfasst die Identität des Quell-Repository.

Ein Lockfile erfüllt auch die separate Richtlinie Aktionen so festlegen, dass sie an eine Commit-SHA voller Länge angeheftet sind für Workflows, die dafür eingebunden sind. Siehe Steuern der Ausführung von GitHub Actions-Workflows.

Nächste Schritte

Um eine Sperrdatei für ein Repository zu erstellen, siehe Sperren von Abhängigkeiten von Actions in den Workflows eines Repositorys.