GitHub Actions Lockfiles vs SHA Pinning: What Does Each Verify?
Compare action references, dependency lockfiles, offline coverage checks, and code review using a small gh-actions-lock experiment.

A workflow contains one uses: line. The action behind it can contain more. Reviewing only the visible reference leaves a second question unanswered: which dependency graph will this job execute?
GitHub Actions dependency lockfiles make that graph more explicit. They do not decide whether its code deserves your trust.
First separate the controls
A full commit SHA names a particular commit in a workflow reference. A dependency lockfile records resolved action dependencies. Review asks whether those dependencies are acceptable for the job’s authority.
GitHub’s October 28 GA announcement describes locking actions and their transitive dependencies, gradual onboarding, and checks for stale records. The tool and enforcement policy are separate surfaces: verify current plan and repository support before designing a rollout.
The current enforcement guide also treats requiring a lockfile and requiring SHA-pinned references as separate policies. Do not assume adopting one automatically enables the other.
| Control | Question it helps answer | Question it does not settle |
|---|---|---|
| Commit reference | Which commit does this reference name? | Is its behavior acceptable? |
| Dependency lockfile | Which supported action dependencies were resolved? | Does it cover every downloaded tool or container? |
| Offline coverage check | Is every recognized reference represented locally? | Is the recorded provenance trustworthy? |
| Network verification | Does the record pass the tool’s current remote checks? | Should this code receive your secrets? |
Break coverage on purpose
We tested the official CLI at v0.4.1 in a temporary local fixture. The starting workflow had one dependency:
name: Coverage fixture
on: push
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6.0.0
- run: printf 'fixture only\n'
From an authenticated GitHub CLI environment, the documented installation is:
gh extension install github/gh-actions-lock
Check gh actions-lock --version because behavior and format can change. In a disposable checkout, generate the dependency record, inspect the diff, and then check coverage:
gh actions-lock
gh actions-lock --verify-local --json
The second command is an offline check. In our fixture it failed before a lockfile existed, passed after generation, and failed again after we added an unlocked actions/setup-node@v6 step.
| Fixture state | Offline result | What changed |
|---|---|---|
| Workflow, no lockfile | Invalid | Checkout reference had no entry |
| Generated lockfile | Valid | The reference was covered |
| Another action added | Invalid | The new reference had no entry |
Local CLI checks, November 5, 2026. These are not hosted runner or organization-policy enforcement results. Initial generation used network resolution; the coverage checks did not.
The useful lesson is not that a green check makes the action safe. It is that you can deliberately create a missing dependency and observe the check reject it.
Read the limitation before trusting the green result
The CLI README distinguishes --verify-local from --verify. The former checks coverage without network access; the latter checks the record against remote information. A record can satisfy one question without satisfying the other.
The same source documents boundaries involving local actions, external reusable workflows, and container images. Follow the current version’s rules instead of assuming “transitive” means every executable input a build might obtain.
A shell step can download a program. An action can run a container. The dependency record’s supported scope does not replace review of those operations.
If uses: and checkout are new to you, practice the checkout action on LabEx first. That activity supplies prerequisites, not a ready-made lockfile-security experiment.
Make an update reviewable
Keep the workflow change and its dependency-record change together. Ask which references were added or moved, why the new commits are appropriate, and whether any job’s authority changed. Test missing coverage as part of learning the control, then confirm the remote verification and enforcement behavior separately in an environment you control.
The PR-trigger audit answers the neighboring question: which code receives which authority? Locking a dependency and limiting its authority are complementary decisions.
References
- Workflow lockfiles GA: release scope and adoption model.
- gh-actions-lock: commands, supported hosts, and limitations; tested CLI v0.4.1.
- Enforce workflow lockfiles: policy scope and rollout considerations. Sources checked November 5, 2026.

