GitHub Actions Lockfiles: What to Review Before Adoption

GitHub Actions workflow lockfiles give reviewers a place to inspect the commits selected for action dependencies, including nested actions. Start adoption with one workflow, inspect the generated changes, and keep a separate inventory of what the job can execute or access outside that action graph.

GitHub announced general availability on 28 October 2026 for Free, Team, Enterprise Cloud, and Enterprise Cloud with data residency. The announcement also warns that locking cannot establish whether a dependency is safe. Release announcement

This guide is a documentation review, not a tested migration. It uses the versioned gh-actions-lock v0.4.0 README alongside current GitHub documentation. Some documentation still carries preview wording, and the sources disagree about reusable-workflow coverage. That uncertainty matters enough to address before copying an adoption recipe.

What changes when you lock action dependencies?

A workflow can name an action through a tag or branch that later moves. GitHub documents a generated file, .github/workflows/actions.lock, which records onboarded workflows and maps dependency references to commits and numeric repository identities. For onboarded workflows, the locked commit is used for execution and allowed-actions checks. Concepts

Consider a hypothetical build workflow that calls a remote composite action, which calls another remote action. Reviewing only the first action’s revision leaves a second question: which revision of the nested action will run? Transitive locking makes that dependency choice visible for review. It does not answer whether either action should receive a deployment credential.

Figure 1. An original conceptual review map, based on the linked documentation and v0.4.0 limitations. The boxes describe review responsibilities, not a tested execution trace or a security guarantee. Reusable-workflow coverage is deliberately marked for verification because the sources differ.

Use the map to divide a pull-request review into manageable questions. One reviewer can trace dependency changes while another checks why the job needs particular access. Neither should infer the second answer from the first review’s green status.

Resolve coverage before removing existing pins

The GA announcement includes reusable workflow references in its coverage description. However, the v0.4.0 README explicitly excludes cross-repository calls at jobs.<id>.uses. We have not resolved that difference through a runtime test. Keep existing full-SHA pins on reusable-workflow calls until the behavior of your adopted version is established. Announcement · Versioned limitations

The same README lists further limits: container images are outside its locking scope; local ./ actions need special handling; and a change to an older commit still reachable in a floating reference’s history is not detected as a rollback. These are reasons to inspect the diff, not reasons to accept a failing check. CLI limitations

For your repository, write down the unresolved cases before onboarding:

Review question	Evidence to retain
Which workflows are covered?	Their entries in the generated file and the verification result.
Which calls need separate revision controls?	The actual reusable-workflow and local-action references, checked against your CLI version.
What is fetched during execution?	Package installs, container references, download commands, and their independent verification.
What access remains?	Job permissions, supplied secrets, deployment environments, and runner configuration.

This is our review checklist. It is not a claim that a lockfile validates every item in the table.

Onboard one workflow and read the whole diff

GitHub documents installing its CLI extension and generating the lockfile for selected workflows. Use an authenticated GitHub CLI in a repository you control, on a review branch. The following commands are documentation-based; we did not run them for this article. Setup guide

gh extension install github/gh-actions-lock
gh actions-lock .github/workflows/ci.yml
git status --short
git diff
cat .github/workflows/actions.lock
gh actions-lock --verify

Replace ci.yml with the workflow you intend to onboard. A newly created, untracked lockfile does not appear in ordinary git diff, so inspect the file itself as well as the tracked changes. The generator can modify workflow references as well as the lockfile, so inspect both. Avoid treating a large machine-generated diff as routine housekeeping. Follow the current help for local-action handling rather than adding an ignore option simply to make the check pass. Setup · CLI help and limits

Our suggested review order is:

1. Confirm that only the intended workflow was onboarded.
2. Explain each newly selected dependency and revision.
3. Investigate unexpected source-identity or backward revision changes.
4. Recheck the workflow’s access and runtime inputs.
5. Preserve the review and verification outcome with the pull request.

If generation fails, retain the error and investigate the unsupported or inconsistent reference. Deleting the lockfile and accepting a newly generated result without comparison loses the history the review needs.

Keep three decisions separate

Verification: v0.4.0 documents --verify as a read-only network check. --verify-local checks offline coverage, not provenance. Do not substitute the latter and describe the result as equivalent. CLI modes

Enforcement: GitHub provides a separate Require lockfile policy. A file in one branch does not establish that every repository or workflow is required to use it. Review the intended policy scope before enabling enforcement; the documentation’s evaluate mode is Enterprise-only. Enforcement guide

Acceptance: decide whether the selected code and its access are appropriate. A verification result cannot make that decision for you. A pinned action can still perform an unwanted operation if the job gives it the necessary capability.

The useful outcome is a specific record: this workflow uses these reviewed action revisions, these other inputs remain separately controlled, and these checks must pass before a change ships. That record is more actionable than a blanket statement that the CI pipeline is now secure.

For a related package-review problem, our Agent Skills security guide explains why reviewing an entry point alone can miss supporting code and update changes.