GitHub Actions Lockfile: What It Is and How to Use It

What is a GitHub Actions lockfile?

A GitHub Actions lockfile is a file, .github/workflows/actions.lock, that records the exact commit for each action and reusable workflow your workflows depend on, including their transitive dependencies. Your workflow can keep a readable reference such as a version tag, but the runner executes the commit recorded in the lockfile [1][2].

The problem it targets is simple. Tags and branches can move after you reviewed a workflow, so a later run can execute different code. If an action is compromised, a moved tag can change what your pipeline runs without any change to your repository [1].

GitHub announced the public preview on 14 October 2026. The changelog was edited the same day to say it is available on GitHub Enterprise Cloud (including data residency), Team and Free plans [1]. The preview is subject to change, and GitHub Enterprise Server is not supported [2].

How workflow dependency locking works

You install the gh actions-lock extension for the GitHub CLI. Running gh actions-lock scans the workflows in .github/workflows, pins each resolvable action to a commit SHA, and writes the lockfile for you to review and commit [1][2].

Adoption is per workflow. Once a workflow is onboarded, every dependency must have a lockfile entry, and GitHub Actions runs the recorded commit even if the tag or branch has since moved [1].

The tool also checks pins rather than trusting them. According to its README, each locked pin is re-checked at job start: the repository was not renamed or transferred, the pinned commit still exists, and it is still in the history of the tag or branch recorded. A failed check blocks the run. This is aimed at impostor-commit attacks, where a commit from a fork is made to look like upstream code [2].

One limit to know about: workflows that use local-path actions (uses: ./something) cannot be onboarded yet, and GitHub calls this a short-term gap. The tool converts same-repository references to a $/ form on fix runs, so check its README for the current behaviour [2].

What a lockfile does not protect you from

GitHub is explicit that locking does not decide whether a dependency is safe. It fixes which commit runs, so you need to review a dependency before you lock it [1].

Our reading, not GitHub's wording: a lockfile turns a silent change into a visible one. If a maintainer's tag is hijacked tomorrow, your runs keep using the commit you reviewed. But if the commit you locked was already malicious, locking preserves it. That is why GitHub's guidance says a lockfile is only a security control if someone reads the diff, and suggests adding actions.lock to CODEOWNERS and requiring a code-owner review [3].

Related note: on 20 October GitHub also put a package firewall into public preview for GitHub Enterprise Cloud. It sits between runners or coding agents and the npm registry and can apply cooldown periods and advisory checks. It covers npm packages only today, and it is a separate control from lockfiles [4].

How to adopt it safely (a practical order)

1. Install the extension with gh extension install github/gh-actions-lock, run gh actions-lock in a non-critical repository, and read the generated diff before committing [2].

2. Add a pull-request check that runs gh actions-lock --verify, which exits with an error if the lockfile is stale. GitHub's docs describe this as a good required check. For a faster local check, gh actions-lock --verify-local --no-fix works offline in a pre-commit hook, but it only confirms every dependency has an entry, not that the pins are trustworthy [2][3].

3. Keep Dependabot managing your actions. When it bumps an action in an onboarded workflow, it regenerates the matching lockfile entry in the same pull request. It will not onboard a workflow that has no entries yet [1][3].

4. Add .github/workflows/actions.lock to CODEOWNERS and require code-owner approval, so a changed SHA is reviewed by the people responsible for build security [3].

5. Only then consider the Require lockfile policy, which blocks runs of targeted workflows that are not onboarded. GitHub's docs say to pilot it first: scope it to repositories already onboarded and start in Evaluate mode, which is available on GitHub Enterprise. Do not use Active mode until you can keep lockfiles current [3].

Is it worth it for a small SaaS team?

Prediction, not fact: for a small team the cost is low and the failure mode is annoying rather than dangerous. You run one command, review one extra file in pull requests, and a stale lockfile is flagged by a check. The benefit is that your deploy pipeline, which usually holds cloud and hosting credentials, stops depending on tags that other people control.

If you ship customer-facing software, treat CI as part of the product's attack surface. Pinning actions, scoping tokens, and reviewing workflow changes are cheap controls compared with the cost of leaked deployment keys. Because the feature is a public preview, expect flags and behaviour to change, and try it first on a repository where a broken build is acceptable.

Frequently asked questions

The short version

A GitHub Actions lockfile pins what your CI runs to commits you reviewed. It does not judge those commits, so pair it with review of the lockfile diff. Start with one repository, add the verify check, and widen from there.

If your pipeline deploys a product you depend on, our SaaS infrastructure cost guide covers the wider running costs, and the services page explains how we scope SaaS builds.