GitHub Actions Lockfile GA: Lock Workflow Dependencies, Know the Limits

What became generally available

GitHub's October 28 changelog moves workflow lockfiles to general availability on GitHub Enterprise Cloud, Enterprise Cloud with data residency, Team and Free plans. The feature entered public preview on October 14, so the GA step came two weeks later. The problem it addresses is familiar if you pin actions by hand: a tag or branch can be moved after you review a workflow, and a later run then executes different code without any change in your repository.

A lockfile lets a workflow keep readable references such as @v4 while runs use the exact commits that were locked. The concept documentation places it at .github/workflows/actions.lock, says it is generated by the gh actions-lock GitHub CLI extension and says it should never be edited by hand. Coverage includes actions and their transitive dependencies, meaning the actions your actions use. That transitive part sits outside the uses: lines you pin in your own workflow files.

For repositories that adopt a lockfile, GitHub says SHA pins in workflow files are no longer necessary, and a lockfile satisfies the "Require actions to be pinned to a full-length commit SHA" policy for onboarded workflows. Do not delete existing pins until a workflow is actually onboarded and verified.

Onboard one workflow first

Onboarding is per workflow, and every dependency of an onboarded workflow must have a lockfile entry. That makes a single low-traffic workflow the right pilot. The extension README documents the install command, which needs an authenticated gh:

gh extension install github/gh-actions-lock
gh actions-lock .github/workflows/ci.yml

The bare gh actions-lock command onboards or fixes the lockfile and writes it. The README lists other modes: --verify runs the same checks without writing, --verify-local checks coverage only without network access, --relock advances moved references such as main or v4, and --no-fix produces a read-only report. A <workflow-path> argument scopes a run to specific workflows. The README names gh actions-lock --help as the authoritative flag list. It supports github.com and GHE.com data residency tenants; GitHub Enterprise Server is not supported.

Replace .github/workflows/ci.yml with the path to your pilot workflow. This is a proposed test, not an executed result. Commit nothing yet, and read the diff.

What to look for in the diff

The documented file has two sections. workflows maps each onboarded workflow file to its dependencies. dependencies records, per reference, the ref it was resolved from, the commit that runs, and the numeric owner_id and repo_id of the source repository, which GitHub checks at run time. The locked commit must be reachable from the recorded tag or branch in the action's own repository; commits that exist only in a fork are rejected at run time.

Review three things for the pilot. First, count the entries against the uses: lines you expect, and look for transitive actions you did not know you depended on. Second, check each new or changed commit: the enforcement guide says a changed SHA means the code your workflows run has changed. Third, watch for rollbacks. The README warns that a lockfile change that moves a floating reference back to an older commit in its history is not detected, so a human has to notice it or you pin exact tags.

That last point is why the lock is not a verdict on the action. GitHub's GA note says lockfiles guard against unexpected dependency changes but do not establish that a dependency is safe. If an AI assistant suggested the action, verify the publisher and repository the way the slopsquatting guide describes for packages before you lock it; a lock faithfully preserves a bad choice.

What the lock does not cover

• Reusable workflows. Calls at jobs.<job_id>.uses are not pinned; the docs say to pin them by full commit SHA. Their own dependencies are covered by the lockfile in the repository that defines them.
• Build inputs. Input parameters, secrets and the runner image are not controlled. The docs put it plainly: the lockfile controls which action code runs on the runner.
• Container images. The README says images are not locked, and an image without an @sha256: digest produces a warning.
• Local actions. Same-repository ./ actions are not followed or locked; one that uses remote actions is a blocking error unless you pass --migrate-local-actions or --ignore-local-actions.

Cache contents are another separate surface; the cache-mode report covers that control. For how these pieces fit an AI-assisted pipeline, see the AI CI/CD guide.

Add a verify check and an owner

The enforcement guide recommends a verify job that runs gh actions-lock --verify on pull requests, used as a required check, so a stale lockfile fails before merge. The repository ships an example, verify-lockfile.yml, whose steps include:

- run: gh extension install github/gh-actions-lock --pin v0.2.0
- run: gh actions-lock --verify

Copy the complete example workflow and adapt it to your repository, then run gh actions-lock again so the verify workflow is itself locked. Dependabot helps with upkeep: for an onboarded workflow it regenerates the matching lockfile entry in the same version-update pull request, but it will not onboard a workflow that has no entries yet.

Next, add .github/workflows/actions.lock to CODEOWNERS and require code owner approval through branch protection or a ruleset. A lockfile diff is a dependency change, and someone who knows your build should approve it.

Trial Require lockfile before enforcing it

GitHub's GA announcement names a Require lockfile policy for enterprise, organization and repository administrators, but the enforcement guide lists GitHub Enterprise Cloud under feature availability. It also limits Evaluate mode to Enterprise Cloud. There, scope the policy to onboarded repositories and workflows and read the results in Policy insights. On Team or Free, use gh actions-lock --verify as a required pull request check; availability of lockfiles alone does not establish access to the enforcement policy.

Two blocking rules matter. In Active mode, any targeted workflow that is not onboarded is blocked, even when other workflows in the same repository are. And if a workflow calls a reusable workflow from a repository that is not onboarded, the calling run is blocked. Inventory cross-repository calls before you switch modes, and keep the verify check after enforcement: the policy blocks runs, while the check tells authors about a stale lockfile during review.