9 min read - GitHub Actions Lockfiles: Approve the Commit That Will Run

On 14 October 2026, GitHub put workflow dependency lockfiles into public preview. A team can keep a readable reference such as actions/checkout@v6 in a workflow while .github/workflows/actions.lock records the exact commit GitHub Actions will run.

That removes one awkward choice from CI maintenance. Reviewers no longer have to choose between a recognisable version tag and an opaque hash in every uses: line. It also creates a new review duty: the lockfile diff now decides which external code runs inside a build, test or deployment job.

GitHub says this directly in its 14 October announcement: locking protects a workflow from an unexpected tag or branch move, but it does not decide whether the locked dependency is safe. For a startup or mid-sized engineering team, the sensible policy is therefore short: no lockfile update merges as generated noise. Review the requested ref, the resolved commit and the job authority together.

What the preview changes

Without a lockfile, Actions resolves a tag or branch when the job starts. The same workflow commit can therefore execute different upstream code on two dates if its reference moved. GitHub's workflow lockfile documentation explains that an onboarded workflow instead runs the commit recorded in the lockfile. Every dependency used by that workflow must have an entry.

The file records more than a hash. Its workflows section links each onboarded workflow to its dependencies; the dependencies section stores the requested ref, resolved commit, repository owner ID and repository ID. Those numeric identities let the runner detect a repository rename, transfer or substitution rather than trusting the displayed name alone.

GitHub also resolves action dependencies used by other actions. Reusable workflow calls are different: their nested dependencies belong to the lockfile in the repository that defines the reusable workflow. A platform team that centralises release jobs must therefore review both the caller's file and the shared workflow repository's file. One green check in the application repository does not describe the whole execution chain.

The preview is available on Free, Team and GitHub Enterprise Cloud plans, including Enterprise Cloud with data residency. The public gh-actions-lock repository states that GitHub Enterprise Server is not supported and warns that its pre-1.0 format, flags and behaviour may change. Adoption should include an upgrade owner and a rollback route, not an assumption that today's CLI contract is permanent.

Review intent and execution as separate facts

A lockfile gives reviewers two useful views of one dependency. The workflow shows human intent, such as “use major version 6.” The lockfile shows execution identity, meaning the commit that will run now.

Neither fact establishes trust. A tag can resolve to a stable commit that contains a dangerous change. A reputable publisher can also ship a release that does more than your job needs. Approval needs a third record: why this repository, ref and commit are acceptable in this workflow with these permissions.

The independent OpenSSF Scorecard guidance recommends hash pinning because maintainers can rename a version tag, together with an update tool so pinned dependencies do not stagnate. GitHub's lockfile supplies the hash pin at runtime while preserving the version reference in YAML. It does not replace the second half of that advice: updates still need to arrive, receive review and move through the pipeline.

Make the generated diff a release gate

Machine-generated does not mean low-risk. Package lockfiles already teach this lesson, yet workflow files deserve stricter handling because an action can receive the repository token, secrets, an OIDC identity, deployment credentials or write access to build outputs.

Assign code ownership for both .github/workflows/** and .github/workflows/actions.lock. Require the same reviewers for a workflow ref and its corresponding locked commit. If the lockfile changes without a declared workflow update, stop and identify why the resolver produced a new value.

Reviewers should open the source comparison between the old and new commits. Read the action metadata and bundled JavaScript or container definition, then check newly added network calls, downloaded binaries, shell commands and permission requirements. A release note helps orient the review; it is not a substitute for the code that will execute.

The SLSA source requirements separate immutable revision identities from human-readable changes and continuous technical controls. They do not certify this GitHub preview, but the distinction is a sound review test: a commit ID identifies the input, a readable diff supports the decision, and a required check keeps the control active after the pilot.

Start with the workflow that can do the most damage

GitHub supports onboarding one workflow at a time. Use that to reduce uncertainty, but choose the first candidate by authority rather than convenience. A documentation check with read-only permissions is easy to migrate; a production deployment exposes the questions the policy must answer.

Inventory each uses: reference in the chosen workflow, including reusable workflows and composite actions. Record the trigger, token permissions, secrets, OIDC settings, environment protection and output destination. Then generate the lockfile on a branch that cannot deploy.

Run four checks before enabling a repository or organisation requirement:

1. Verify that a normal job executes the recorded commits and still produces the expected artifact or test result.
2. Change a workflow dependency without updating the lockfile and confirm that the verification gate fails.
3. Generate a legitimate dependency update, inspect both diffs and confirm that the old commit remains available for rollback.
4. Exercise the response path for an upstream compromise without using production credentials.

This pilot should produce evidence, not a screenshot of a passing run. Keep the workflow commit, lockfile commit set, CLI version, test run and reviewer. If the team cannot recover those facts during an incident, the inventory has little operational value.

Do not turn pinning into neglect

Pins stop silent movement; they also stop beneficial movement. The OpenSSF Pinned-Dependencies check warns that pinned software can miss security fixes and recommends automated update notifications plus timely upgrades.

Dependabot version updates now regenerate the matching lockfile entry when they update an action reference in an onboarded workflow, according to GitHub. Keep that pair in one pull request. The update should show the requested version change, the new commit and the tests that ran against it.

The CLI separates routine and exceptional movement. A normal run keeps existing pins. --relock resolves refs again when an upstream moved legitimately, while --accept-moved can accept suspicious movement that would otherwise remain an error. Restrict the last option to an incident or documented recovery procedure. A command whose purpose is to override an alarm should never be the default update recipe.

Set an update service level that fits the workflow's authority and exposure, but do not invent a universal number. A public action used in an internet-facing release path may need a different response from an internal lint job. Name the owner, the event that starts review and the person who may approve an emergency pin change.

Pair the lock with the rest of the workflow boundary

Lockfiles address dependency identity. They do not reduce GITHUB_TOKEN permissions, remove secrets, isolate untrusted pull requests, verify downloaded artifacts or stop a reviewed action from behaving badly. Review those controls beside the lockfile rather than claiming that the CI supply chain is now secure.

Cache state deserves the same treatment. A locked action can still restore bytes written by another workflow. Our GitHub Actions cache boundary guide shows how to trace producers, consumers and release authority before granting cache writes.

Small teams do not need a large governance programme for this. A CODEOWNERS rule, a required verification job, Dependabot updates and a brief pull-request template can cover the decision. The template should ask what changed upstream, which commit will run, what authority the job has, which test passed and how to revert.

Once the pilot is stable, enable GitHub's preview “Require lockfile” policy at the narrowest useful level and expand workflow by workflow. An organisation-wide switch before shared workflows, exceptions and recovery commands have owners can trade one silent failure mode for a visible stream of blocked builds.

Exceev's Custom Engineering and consulting services can help teams map CI trust boundaries and build a staged adoption plan. The repository owner remains responsible for dependency approval, access policy and incident decisions.

Sources and limitations

We opened and reviewed every source below on 15 October 2026.

• GitHub's 14 October announcement establishes the public preview, plan availability, lockfile policy, gradual onboarding and Dependabot integration. It also states that locking does not assess dependency safety.
• GitHub's workflow lockfile documentation defines runtime resolution, recorded repository identity, transitive coverage and the reusable-workflow boundary.
• The gh-actions-lock repository documents CLI verification, relocking, moved-ref handling, current support limits and the pre-1.0 warning.
• OpenSSF Scorecard's pinning guidance recommends hash pins with an update tool; its Pinned-Dependencies check explains the update risk created by stale pins.
• SLSA's source requirements provide independent definitions for immutable revisions, readable changes and continuous technical controls.

GitHub is the primary source for its preview. OpenSSF and SLSA do not certify GitHub's implementation or Exceev's proposed review method. We did not test the preview in a production repository, inspect a customer's actions or measure migration effort. The format, supported platforms and policy behaviour may change during the preview, so verify the current documentation before enforcing it.