GitHub Actions lockfiles enter public preview, aimed at replacing inline SHA pinning

GitHub moved workflow dependency lockfiles for Actions into public preview on October 14, 2026, making the feature available on GitHub Enterprise Cloud (including data residency), Team and Free plans, according to a write-up on dev.to. The feature produces a single lockfile per repository that records the exact commit behind every action a workflow uses, transitive dependencies included, and GitHub now says repositories that adopt it no longer need to pin commit SHAs inline in their workflow files.

The problem lockfiles address

Workflow steps routinely reference actions by mutable tags such as @v4 or @v1, each of which is simply a git ref in another team's repository. The commit behind a tag can move after reviewers have approved the workflow, and nothing in your repository records which commit was actually reviewed. The conventional remedy is to pin each action to its full commit SHA — an approach required, for instance, by Lullabot's architecture decision record — with tools such as Renovate, Dependabot, pinact and ratchet keeping those pins fresh, and frizbee converting tags to SHAs. As Andrew Nesbitt has pointed out, though, a SHA pin secures only the outermost action: a helper action it calls by tag can still change underneath you.

What the lockfile captures

Every repository gets one file at .github/workflows/actions.lock, generated by the gh-actions-lock CLI extension (installed with gh extension install github/gh-actions-lock, and requiring write access). GitHub's documentation says the file must never be edited by hand. Workflows are enrolled individually or all at once. The file contains a workflows section mapping each enrolled workflow to its dependencies, and a dependencies section where each entry stores the ref the workflow names, the resolved commit in sha1-... form, and the owner and repository IDs that let GitHub confirm at run time that the repository behind a name is still the one you locked. Actions invoked inside composite actions — invisible at the workflow level — appear under a uses list on their parent entry. The dev.to author observes that the format carries no integrity or content hash field, only the commit, though GitHub does not state this outright.

Enforcement comes in four parts

Generating the lockfile, onboarding a workflow, running gh actions-lock --verify in CI, and the 'Require lockfile' policy are four distinct controls, and only the policy prevents runs of workflows that nobody has onboarded. Once enrolled, every action a workflow uses must be present in the lockfile. At job start, GitHub checks source-repository identity, the pinned commit, and full-version tags; the released CLI distinguishes a rename or transfer that preserves the repository ID, which produces a warning, from an entirely different repository hiding behind the same name, which blocks the run.

A hands-on run

The dev.to author enrolled a release workflow using gh-actions-lock v0.2.0 (gh 2.102.0 on Linux). The tool pinned three actions plus two transitive ones — the transitive pair originating inside the composite actions/attest-build-provenance action — and rewrote the workflow's references from @v4 and @v1 to the full-version tags @v4.4.0 and @v1.4.4. With the lockfile committed, gh actions-lock --verify reported the workflow valid and exited cleanly.

Limits and maturity

The protection has clear boundaries. Dependencies inside reusable workflows you call are not covered, container images pulled by tag are not locked, and a lockfile says nothing about whether the pinned code itself is trustworthy. The CLI is pre-1.0 — its file format, flags and behavior may change between releases — and GitHub Enterprise Server is not supported. Documentation is inconsistent too: the announcement carries an editor's note correcting plan availability to include Team and Free, while the setup guide still describes the feature as GitHub Enterprise Cloud. Development is moving quickly: v0.2.0 arrived October 12, 2026, and v0.3.0, released October 22, changed local-action handling, added container-image warnings and tightened verification. The published test walkthrough describes v0.2.0 and was not rerun against v0.3.0.

Why it matters

Anyone who owns a CI workflow has faced the trade-off between readable @v4 tags and the audit trail of SHA pinning, plus the tooling burden of keeping many pins current across dozens of workflows. Lockfiles consolidate that into one machine-generated, reviewable diff, and they close the transitive-action gap that inline pinning leaves open. Given the preview status, the unsupported platforms and the reusable-workflow and container-image gaps, the sensible move is a bounded pilot on one workflow — and to keep SHA pins anywhere the lockfile does not reach.