GitHub Actions Gets Lockfiles, but Shared Workflows Need Their Own
GitHub introduced workflow dependency lockfiles in public preview on October 14, 2026, giving Actions users a way to keep readable dependency references while running recorded commits. The feature addresses a quiet source of change in automated builds: an upstream tag or branch can move even when your own workflow file has not changed.
GitHub's updated announcement lists Free, Team, Enterprise Cloud, and Enterprise Cloud with data residency as eligible plans. Its setup page still labels availability as Enterprise Cloud, so the announcement and documentation are not yet fully aligned. The extension's repository explicitly excludes GitHub Enterprise Server. These are preview capabilities, not a general-availability release.
The lockfile covers more than the first action
According to GitHub's conceptual guide, .github/workflows/actions.lock records the dependencies used by onboarded workflows and the commits those references resolve to. It also stores numeric owner and repository identifiers, which GitHub checks to establish that the source repository is still the one originally locked. The file is generated by the gh actions-lock CLI extension, not maintained by hand.
Coverage includes transitive action dependencies: actions invoked by other actions. There is an important boundary, however. A caller's lockfile does not cover the internal dependencies of a reusable workflow in another repository. Those belong to the lockfile where that reusable workflow is defined.
Consider a hypothetical product repository that calls a release workflow maintained in a central engineering repository. Locking the caller is only one part of that arrangement. The central repository needs its own onboarding and maintenance process. GitHub's setup guidance recommends starting with repositories that provide shared workflows.
Pilot one workflow and review the whole diff
GitHub documents a per-workflow path for adoption. After installing the GitHub CLI, a maintainer can install the extension and target a single workflow from the repository root. In this example, ci.yml stands for an existing workflow selected for the trial:
gh extension install github/gh-actions-lock
gh actions-lock .github/workflows/ci.ymlDo not review only the new lockfile. The setup guide says the extension can rewrite action version references and migrate same-repository action references. It also changes how allowed-actions policies are checked: onboarded workflows are evaluated against locked commit SHAs, so an allowlist entry that names only a tag may no longer match. Check policy compatibility before merging.
The extension README documents gh actions-lock --verify as a non-writing check suitable for CI. Its offline --verify-local option checks coverage, not whether recorded entries are trustworthy. The distinction matters when deciding what a green verification check actually establishes.
Pins are deliberately retained during normal runs rather than automatically following an upstream branch. The README describes --relock for refreshing references and warns that the pre-1.0 tool's format, flags, and behavior may change. Treat a refresh as a dependency update to review, not a routine way to silence a failed check.
Updates still need a review path
Dependabot's documentation says that version updates for actions in an onboarded workflow also regenerate the corresponding lockfile entry in the same pull request, without additional lockfile configuration. That keeps the workflow reference and recorded commit together. Dependabot version updates must still be enabled; adding a lockfile is not a substitute for configuring dependency maintenance.
For a small team, a useful trial is one ordinary test workflow, an owner for reviewing dependency changes, and a clear check of what happens when verification fails. After the first successful run, inspect the generated changes and the update process before extending the rollout to deployment workflows. This is a proposed adoption approach, not a reported test result.
A fixed commit is not a safety verdict
GitHub explicitly cautions that locking does not establish whether an action is safe. A malicious or vulnerable revision remains malicious or vulnerable when pinned. The benefit is a controlled dependency choice, not an audit of what that code does.
GitHub's security guidance still calls for reviewing action source and limiting workflow credentials. Keep those checks alongside lockfiles. Nor should a workflow dependency lockfile be read as proof that every build input is fixed: the documented scope is actions and reusable workflows, not every package, tool, or external resource that their commands might fetch.
The practical change is that more of the automation's dependency choices can become explicit, reviewable files. To make that useful, teams need to follow the boundary across shared repositories and keep the update path working after the first lockfile lands.
Sources
// keep reading