Workflow dependency lockfiles

A lockfile pins every action your workflows depend on to a verified commit, so the code you reviewed is the code that runs.

Neste artigo

Observação

Workflow dependency lockfiles are in prévia pública and subject to change.

Why lock workflow dependencies?

When a workflow references an action by a tag or branch, such as uses: octo-org/deploy-action@v3 or uses: octo-org/deploy-action@main, GitHub Actions resolves that reference to whatever commit the tag or branch points to at run time.

Tags and branches can move, so the code that runs is not guaranteed to be the code that the workflow author originally reviewed. If an upstream maintainer's account is compromised and a tag is repointed, your repositories could run malicious code.

A workflow dependency lockfile pins a commit SHA to every action (including transitive dependencies) and reusable workflow your workflows depend on. This gives you:

  • Reproducible builds
  • Reviewable dependency changes and Dependabot version updates
  • An auditable inventory of your CI/CD systems' dependencies

How does the lockfile work?

The lockfile is defined in a repository at .github/workflows/actions.lock. It's generated by gh actions-lock, a GitHub CLI extension, and should never be edited by hand.

You can onboard a repository's workflows to the lockfile one at a time or all at once. After a workflow is onboarded:

  • Every action dependency the workflow uses must be present in the lockfile.
  • The locked commit is what runs when the workflow executes, and what allowed actions policies check. This commit must exist within a branch of the source repository.

A lockfile covers the workflows in its own repository. It extends to transitive dependencies (actions that your action dependencies use), except for dependencies of reusable workflow calls. A reusable workflow is covered by the lockfile of the repository where it is defined.

What does the lockfile record?

The lockfile has two sections. workflows records which dependencies each onboarded workflow uses, and dependencies records which commit each of those references resolves to.

# This file is machine-generated by `gh actions-lock`.
# Do not edit by hand; run `gh actions-lock` to update.
version: 'v0.0.2'
workflows:
    '.github/workflows/ci.yml':
        - 'octo-org/[email protected]'
dependencies:
    'octo-org/[email protected]':
        ref: 'v3.1.0'
        commit: 'sha1-...'
        owner_id: 44036562
        repo_id: 197814629

Each dependency records:

  • ref: The reference the workflow uses, such as a tag or branch.
  • commit: The exact commit the reference resolved to. This is the code that will run.
  • owner_id and repo_id: The numeric identity of the source repository. GitHub Actions uses these to confirm at run time that the repository behind the name is still the one you locked.

How do lockfiles compare with SHA pinning?

GitHub has historically recommended pinning third-party actions to a full-length commit SHA in your workflow files. For repositories that adopt a lockfile, SHA pinning within workflow files is no longer necessary. The lockfile is the better option because it supports transitive dependencies, makes workflow files easier to read, and records the identity of the source repository.

Next steps

To create a lockfile for a repository, see Locking action dependencies in a repository's workflows.