GitHub Actions Lockfiles Pin the Workflow Behind a Readable Tag

A CI workflow can say uses: vendor/action@v2 and still run different code months later if the maintainer moves that tag. GitHub’s new workflow lockfiles address that gap without forcing every workflow file to become a wall of commit hashes. The lockfile records the resolved revisions—including nested action dependencies—while the main YAML can remain readable. That makes builds more predictable, but a fixed version is not the same as a safe version.

The problem is a moving reference

GitHub Actions workflows often refer to an action by a release tag or branch. Those labels are convenient for humans, but a tag can be repointed. If a dependency reference changes between two runs, the workflow may execute code that is not visible in the workflow file’s diff. Security guidance has long recommended pinning actions to full commit SHAs; the tradeoff is that raw SHAs are less readable and need maintenance when teams intentionally upgrade. ^{[1] [2]}

The new mechanism uses the GitHub CLI extension gh actions-lock to generate .github/workflows/actions.lock. GitHub says the lockfile covers direct actions, transitive dependencies and reusable workflow references. For an onboarded workflow, Actions requires each dependency to be present and executes its recorded commit. Dependabot can update the lockfile entry in the same pull request as an action version change, and administrators can require lockfiles or check whether one is stale. ^{[1] [3]}

The practical benefit is an auditable link between a readable reference and the code that a workflow will resolve. Reviewers can see the intended version in YAML and inspect the exact commit in the lockfile. A stale reference becomes a visible update rather than a silent change at build time.

Pinning narrows one kind of uncertainty

A lockfile helps answer: “Which revision did this run execute?” It does not answer: “Should we trust that revision?” A pinned commit may contain malicious code, a vulnerability or an action that requests more permissions than its job requires. A maintainer account can be compromised before a release is pinned, and a malicious dependency may enter through an intentional-looking update. GitHub’s own announcement makes this limitation explicit: lockfiles protect against unexpected dependency changes, but do not determine whether a dependency is safe. ^[1]

That distinction matters during review. A Dependabot pull request that updates an action and its lockfile has changed executable code, even if the diff looks mechanical. Review the action source and release notes, check which permissions the workflow grants, and verify that untrusted pull-request content cannot reach a privileged job. Locking improves repeatability; it does not replace least privilege, code review or build provenance.

Software supply-chain frameworks such as SLSA describe provenance as verifiable information about where, when and how an artifact was built. Dependency resolution is one part of that story, not the whole chain. A lockfile helps record a stable input; provenance and verification help connect those inputs to an output artifact and the builder that produced it. ^[4]

A low-risk adoption path

Start with a workflow whose dependencies are well understood and whose trigger does not run with deployment credentials. Generate the lockfile using the supported extension, inspect the generated entries, and commit the workflow and lockfile together. Enable the stale-lock check in CI, then test what happens when an action is deliberately updated. Only after the review process is clear should an organization enforce the requirement across a larger repository set. ^{[1] [2]}

Next, inventory where Actions can write: repository content, pull requests, packages, deployments and organization settings. Prefer job-level permissions and grant only what the workflow needs. An immutable pin can still run with an overly powerful token; the blast radius comes from both the code and its authority.

Finally, write down who may approve a dependency update and how to respond if a pinned action is later found compromised. Pinning can make the incident easier to reconstruct, but response still requires identifying affected workflows, replacing the revision, rerunning builds and evaluating any artifacts produced while it was in use.

What teams gain

The feature is most valuable for repositories where workflows are part of the production software supply chain and tags are otherwise trusted implicitly. It reduces one source of nondeterminism, makes nested dependencies easier to inspect and gives platform teams an enforcement point. It is less useful as a compliance checkbox if nobody reviews updates or if workflows still have broad permissions.

GitHub’s GA release preserves the readability people want while adding an exact revision record for what runners execute. That is a meaningful usability improvement to commit pinning. The right mental model is a ledger of resolved inputs: useful evidence for predictable builds, but only one control among dependency review, narrowly scoped credentials, protected environments and verifiable build provenance.