← Back to all posts

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.

Blue and violet workflow arrows linked by rounded dependency nodes

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.

A workflow references an action, which can reference other actions; a dependency record and code review answer different questions

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

Recorded CLI results show invalid, valid, then invalid coverage as the synthetic workflow changes

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