GitHub Actions adds workflow lockfiles via gh actions-lock

A blog post on hugovk.dev announces that GitHub Actions now supports workflow lockfiles and shows how the author set them up.

The background: because GitHub Actions are fetched from Git, the previous advice was to pin each action to a full commit SHA instead of a tag. Tags are mutable, so they are open to supply-chain attacks in which an attacker points a previously safe tag at malicious code. The old-style workflow in the post pins actions/checkout and j178/prek-action to long SHAs, with the version in a trailing comment (v7.0.1 and v3.1.0).

The setup has a few steps. First, install the extension for the gh CLI with gh extension install github/gh-actions-lock. Then, in the repo, run gh actions-lock; in the author's repo, with a single workflow, it printed "All 1 workflows valid". The workflow files now use plain version tags (actions/checkout@v7.0.1, j178/prek-action@v3.1.0), and a lockfile appears at .github/workflows/actions.lock. The file header says it is machine-generated and should not be edited by hand. It lists each workflow with the actions it uses, and under dependencies it records, for each action, the ref (the tag), the resolved commit as a sha1 hash, and the owner and repo IDs. The example lockfile has version 'v0.0.3'. The author commits both the modified workflows and the new lockfile.

Renovate and Dependabot already support lockfiles, the author says, so their periodic updates will also update the lockfile. The author's reminder: use cooldowns.

GitHub also recommends verifying lockfiles in CI, to make sure the file is up to date and not corrupt. GitHub suggests copying a verify-lockfile.yml workflow into the repo. The author instead added it to an existing lint workflow as its own job, so it runs independently and in parallel. That job runs on the lightweight ubuntu-slim runner, installs the extension pinned with --pin v0.4.1, and runs gh actions-lock --verify. A comment in the workflow says the job fails when the lockfile is out of sync with the workflows or when a locked pin no longer verifies upstream. The author notes that the pinned extension version will have to be updated at some point, or the update automated, and leaves that for another time.

One catch: adding a verify job changes the actions used in a workflow, so the lockfile needs relocking with gh actions-lock. Nothing changes when the job is added to lint.yml, since actions/checkout is already locked there. A new file such as verify-lockfile.yml would need a relock, and the CI will flag it.

Finally, the author strongly recommends zizmor, a security linter for GitHub Actions. Versions before v1.32.0 tell you to hash-pin actions; v1.32.0 is the first to support lockfiles. The author runs zizmor through prek and bumps rev to v1.32.0 in .pre-commit-config.yaml. Then commit and push.

Key facts

GitHub Actions now supports workflow lockfiles: workflows use tags like actions/checkout@v7.0.1, and .github/workflows/actions.lock records the resolved commit SHA for each.
Setup is gh extension install github/gh-actions-lock, then gh actions-lock in the repo; commit the changed workflows and the new lockfile.
Renovate and Dependabot already support lockfiles, per the author, who also advises using cooldowns.
GitHub recommends verifying lockfiles in CI; the author runs gh actions-lock --verify in a separate job on the ubuntu-slim runner, pinned to extension v0.4.1.
zizmor v1.32.0 is the first version to support lockfiles; earlier versions tell you to hash-pin actions.

Why it matters

Until now the standard defence against tag tampering in GitHub Actions was to pin every action to a full commit SHA, which makes workflows hard to read. The post describes lockfiles as a way to keep human-readable version tags in the workflow while a separate file records the exact commit each tag resolved to. The risk it addresses is that tags are mutable, so an attacker can point a previously safe tag at malicious code.

Who it affects

Anyone who maintains GitHub Actions workflows, especially repos that already hash-pin actions. The post also touches users of Renovate and Dependabot, which the author says already support lockfiles, and users of zizmor, who need v1.32.0 or later to get lockfile support.

How to use it

Install the extension with gh extension install github/gh-actions-lock, run gh actions-lock in the repo, and commit the modified workflows plus .github/workflows/actions.lock. To verify in CI, copy GitHub's suggested verify-lockfile.yml or add a job that installs the extension (the author pins --pin v0.4.1) and runs gh actions-lock --verify. Relock whenever you add or change actions in workflows. If you use zizmor, update it to v1.32.0 or later; in a pre-commit setup that means setting rev: v1.32.0. Keep cooldowns on Renovate or Dependabot updates.

How solid is it

This is one practitioner's walkthrough, with real command output, a diff and an example lockfile, rather than GitHub's own documentation. The lockfile header points to https://gh.io/actions-lockfile for docs. The post gives no date for the feature and does not say whether it is in preview, generally available, or limited to certain plans.

Risks and caveats

The extension version pinned in the author's CI job will go stale, and the author has not yet worked out how to automate updating it. Adding a new workflow file, such as a separate verify-lockfile.yml, means the lockfile must be regenerated or the CI check will fail. No real attack incident is cited; the supply-chain risk is described in general terms, and the post gives no adoption or performance figures.

“GitHub Actions now supports workflow lockfiles.”

— Lock your GitHub Actions, hugovk.dev