GitHub Actions Lockfiles: Keep CI Running the Code You Reviewed

Learn how GitHub Actions workflow lockfiles pin direct and transitive actions, how to adopt them safely, and what they do not cover.

Developer Tools & Security•~7 min read•November 13, 2026•By QZ-L Editorial
#GitHub Actions#CI/CD#Supply Chain Security
Looking for related guides? Start with the qz-l Learning Center and explore more tutorials in this topic cluster.

A GitHub Actions workflow can look pinned while still depending on moving references. A step such as uses: actions/checkout@v6 is readable, but the tag can point to a different commit later. The same problem can exist one level deeper: an action you call can use other actions that your workflow never names directly.

GitHub Actions workflow dependency lockfiles are designed for this gap. The feature became generally available on October 28, 2026. A generated lockfile records the commits and repository identities behind the action references in an onboarded workflow, including transitive action dependencies. GitHub then checks those records when the workflow runs.

This is not a replacement for reviewing third-party code. It is a way to make the code you reviewed the code your CI continues to execute.

Why readable action tags are not enough

Workflow files commonly use tags or branches:

steps:
  - uses: actions/checkout@v6
  - uses: actions/setup-node@v6

Those references are convenient to read and update, but they are not immutable. A maintainer can move a tag, a branch naturally advances, or a compromised account can change what a reference resolves to. A later run could therefore execute different action code without a change in your repository.

Using a full commit SHA directly in every workflow step reduces that risk, but it makes workflows harder to read and update. It also does not automatically describe the dependencies used inside a third-party action.

A workflow dependency lockfile provides a middle path: keep the readable reference in the workflow, while recording the exact commit that GitHub should run.

What the lockfile pins

The generated file is .github/workflows/actions.lock. It has a workflows section listing the dependencies used by each onboarded workflow and a dependencies section containing the resolution data for each reference.

A simplified coverage entry looks like this:

version: 'v0.0.3'
workflows:
    '.github/workflows/ci.yml':
        - 'actions/checkout@v6'

The real file also has a dependencies section with the resolved ref, exact commit, owner_id, and repo_id for each action. The commit value is the code that runs, while the numeric repository IDs help GitHub confirm that the repository behind the action name is still the repository that was locked. The file is machine-generated; do not copy a hand-written example into a real lockfile or edit generated entries by hand.

Lockfiles cover actions called from workflow steps, including direct and transitive dependencies. They do not pin every input to a build. A lockfile does not select the runner image, freeze downloaded packages, inspect an action for malicious behavior, or prove that the action is safe. Those remain separate supply-chain and build-reproducibility concerns.

A cautious onboarding sequence

Before generating anything, review the action references already present in your workflows. Locking a currently compromised or unreviewed action only makes that unwanted code more consistent.

Install the GitHub CLI extension from the official repository:

gh extension install github/gh-actions-lock

From the repository root, a full onboarding run is:

gh actions-lock

You can onboard one workflow first:

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

The extension resolves the references, writes .github/workflows/actions.lock, and may make workflow references more specific. For example, a broad @v6 reference can be rewritten to the particular version it resolved. Review the complete diff, not just the lockfile:

git diff -- .github/workflows

Check especially the changed commit, owner_id, and repo_id fields. A changed commit is a dependency change and deserves the same review as a version bump. A changed repository identity is unusual and should be investigated before merging.

If your repository uses an allowlist for Actions, check it before committing the lockfile. Once a workflow is onboarded, policy checks use the locked commit rather than the tag. An allowlist that only names actions/checkout@v6, for example, may need to allow the corresponding repository or commit pattern.

Verify without rewriting files

Locking is useful only if it stays aligned with the workflow. The extension provides separate modes for different points in the development cycle:

# Network-backed validation before a change is merged
gh actions-lock --verify

# Offline coverage check for a local pre-commit check
gh actions-lock --verify-local

# Read-only report without fixing files
gh actions-lock --no-fix

The offline mode answers a narrower question: does every relevant uses: reference have a lockfile entry? It does not verify that the recorded commit is still reachable from the reference or that the source repository identity matches. Use the network-backed verification for provenance checks before merging.

For CI, a repository can run a verification command and fail when the lockfile is stale. The exact workflow should be reviewed for the repository's authentication and permissions; a conceptual step is:

- name: Verify workflow lockfile
  run: gh actions-lock --verify

This example was not run for this article. It illustrates the documented command, not a claim that it works in every runner image or repository configuration.

Keep updates intentional

Locking should not turn dependency maintenance into a manual guessing game. GitHub documents Dependabot integration for onboarded workflows: when Dependabot updates an Action reference, it can regenerate the matching lockfile entry in the same pull request. Review that pull request as a dependency update, including the action's release notes and the resulting commit.

References can also move. A branch or partial version such as main or v6 can advance upstream while the lockfile continues to hold the earlier commit. The extension reports this as a moved reference; advance it deliberately with:

gh actions-lock --relock

A full version tag is stricter: if the tag no longer points at the locked commit, verification reports an error. Rewritten history is more serious. The extension documents an --accept-moved option for cases where you have investigated the upstream history, but it should not be used automatically in CI.

The safest routine is therefore:

  1. Review the upstream change.
  2. Update the workflow reference or relock it intentionally.
  3. Inspect the changed commit and repository identity.
  4. Run verification.
  5. Merge the workflow and lockfile together.

Important boundaries

Reusable workflows

A call at the job level is different from an action used in a step:

jobs:
  deploy:
    uses: example-org/shared-workflows/.github/workflows/deploy.yml@v4

The caller's lockfile does not lock the reusable workflow's internal dependencies. The repository that defines the reusable workflow owns its lockfile. If you maintain shared workflows, onboard those repositories too, and consider referencing the reusable workflow by a full commit SHA.

Local actions

The extension cannot follow a local uses: ./path action, because that path runs from the checked-out workspace and may contain its own dependencies. The documented --migrate-local-actions option can rewrite same-repository references to the $/ form, which runs the action at the workflow's commit. Alternatively, you can explicitly keep local actions and handle their dependencies, but that requires careful review because missing entries can make a job fail at runtime.

Do not pass migration flags blindly. The ./ and $/ forms have different behavior, so inspect every rewritten workflow and action.yml file.

Containers and other inputs

Container images are not pinned by the Actions lockfile. If a workflow runs an image, use the image supply-chain practice appropriate to your environment, such as a reviewed immutable digest. Likewise, lockfiles do not freeze package-manager dependencies, downloaded tools, scripts, or the runner image.

Availability and hosting

GitHub documents workflow lockfiles for GitHub.com plans including Free, Team, and Enterprise Cloud variants. The official extension README states that GitHub Enterprise Server is not supported. Confirm availability and policy behavior for your hosting environment before designing an organization-wide rollout.

When to adopt them

Lockfiles are particularly valuable for workflows that can publish packages, build release binaries, deploy infrastructure, or handle production credentials. Start with one representative workflow, review the generated changes, and add verification before onboarding the rest.

For larger organizations, the Require lockfile protection can enforce onboarding for targeted workflows. Stage that rollout: generate and verify lockfiles first, observe policy insights, then activate enforcement. Otherwise, a policy can block workflows that have not yet been prepared.

The goal is not to pretend that a pinned action is trustworthy. The goal is to make an unexpected action change visible, reviewable, and stoppable before it becomes a silent change to your CI.

References

Related Posts

GitHub Actions Is Blocking pull_request_target by Default: What to Change Before December

Prepare public GitHub repositories for the December 2 pull_request_target protection with safer workflow patterns and a focused migration checklist.

GitHub Actions Workflow Logs: Detect and Respond to Leaked Secrets

Enable GitHub workflow log secret scanning carefully, review preview gaps, and revoke leaked credentials with a practical response checklist.

Catch Secrets Before Merge: GitHub's New Copilot Review Path

Use GitHub's preview secret scanning in Copilot security review to catch credentials in code changes before they reach a pull request.