ReleaseLock learn

GitHub Actions workflow lockfiles are GA: what actions.lock locks and what it doesn't prove about release swaps

By Cassie Crossley · Published November 6, 2026 · Sources checked November 6, 2026 (PT)

GitHub made workflow dependency lockfiles generally available on October 28, 2026. They pin direct and transitive Actions to commits while letting you keep readable tags in YAML. They do not prove that your published release assets cannot be swapped.

What .github/workflows/actions.lock actually locks

According to GitHub's GA announcement, lockfiles are available on GitHub Free, Team, Enterprise Cloud, and Enterprise Cloud with data residency. You can keep tag and branch references in workflow files while the runner uses the recorded commits, rather than silently following a moved reference.

GitHub's lockfile reference explains the boundary:

After you onboard a workflow, every Action dependency it uses must have an entry, and the locked commit is what runs. This is a record of which Action code will run, not a verdict that the code is safe.

How to adopt it gradually

GitHub's adoption guide recommends checking your Action versions and enabling Dependabot for GitHub Actions before generating the lockfile. If you maintain shared reusable workflows, onboard their source repositories too.

Install the GitHub CLI extension, then run it from the root of your repository:

gh extension install github/gh-actions-lock
gh actions-lock

To start with a single workflow instead of all workflows, pass its path:

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

Review the full diff before committing. The extension generates .github/workflows/actions.lock and may rewrite uses references to more specific version tags without changing their resolved commits. Never edit the lockfile by hand. Fix the workflow and regenerate it instead.

If your repository has an allowed-Actions list, check it before committing: GitHub evaluates onboarded workflows against locked SHAs, so an allowlist entry pinned to a tag no longer matches. GitHub's guide says to use a wildcard or the full commit SHA.

Local Actions need care

The extension does not follow or lock uses: ./… local paths, which run from the runner's checked-out workspace. GitHub documents --migrate-local-actions to rewrite these to $/… same-repository references at the workflow's commit, so their dependencies can be locked. It also documents --ignore-local-actions, but missing entries for an Action used by a local Action can still make the job fail. Review the behavior change before migrating.

Dependabot sync and --verify

When Dependabot opens an Action version update for an onboarded workflow, it regenerates the matching lockfile entry in the same pull request, without extra lockfile configuration. It does not onboard workflows that have no lockfile entries yet. Re-run gh actions-lock when adding workflows or changing their dependencies (GitHub adoption guide).

Use this read-only check in CI to catch a stale lockfile:

gh actions-lock --verify

GitHub's enforcement guide says the check fails if the lockfile is stale, making it useful as a required pull-request check. It does not modify files.

Enforce with Require lockfile

Enterprise, organization, and repository administrators can use the Require lockfile policy. GitHub recommends a pilot scoped to repositories and workflows that are already onboarded. Evaluate mode is available only on GitHub Enterprise Cloud. Do not switch to Active until every targeted workflow is covered and you have a way to keep lockfiles current (GitHub enforcement guide).

Active enforcement blocks targeted workflows that are not onboarded, even workflows without uses: dependencies. Called reusable workflows also need coverage in their own repositories. Put .github/workflows/actions.lock under CODEOWNERS review and require code-owner approval. A changed commit is a dependency change; investigate a changed owner_id or repo_id before merging.

Lockfile vs pinning Actions by SHA

For workflows that adopt a lockfile, GitHub says full-SHA pinning inside the workflow YAML is no longer necessary. Its comparison favors lockfiles because they cover transitive Action dependencies, preserve readable workflows, and record repository identity.

An onboarded lockfile also satisfies GitHub's separate Require actions to be pinned to a full-length commit SHA policy for those workflows. Require lockfile is a separate setting, and both policies can remain enabled during rollout. This does not remove the need to SHA-pin reusable-workflow calls.

What it does not prove about release-asset swaps

Locking the Actions that build or publish a release does not make the published GitHub Release assets immutable. GitHub's own warning is clear: lockfiles protect against unexpected dependency changes, but they do not determine whether a dependency is safe. Review it before locking it (GA announcement).

After locking workflows, still enable immutable releases and verify artifacts. ReleaseLock fits at that release layer: use the directory to check a tool's release lock status. A workflow lockfile and a release lock answer different questions: which Action code ran, and can the published release be changed afterward?

Locking Actions does not make the package a workflow publishes safe either. See what bee-js 13.3.0 showed about npm provenance.

A lockfile also would not stop an npm install hook added to a repository's own package.json. See how wfx-loot got past GitHub's workflow hold.

A lockfile shows which Action code ran, not what a run printed to its logs. For GitHub's new log scanning, see secrets in GitHub Actions logs.

Quick answers

What is a GitHub Actions workflow lockfile?

.github/workflows/actions.lock records the commits for direct and transitive Action dependencies. For an onboarded workflow, the runner uses those locked commits, subject to GitHub's repository-identity and reachability checks.

When did workflow lockfiles become generally available?

GitHub announced general availability on October 28, 2026, on Free, Team, Enterprise Cloud, and Enterprise Cloud with data residency.

Do lockfiles pin reusable workflows?

No. Pin reusable-workflow calls to full commit SHAs separately. Their Action dependencies are covered by the lockfile in the repository where the reusable workflow is defined, not the calling repository's lockfile.

Does a lockfile stop GitHub release assets from being swapped?

No. It locks Action dependencies, not published release assets. Immutable releases and artifact verification are separate controls. A locked pipeline can still publish to an unlocked release.

How do I enforce lockfiles across an org?

Pilot the Require lockfile policy on onboarded repositories and workflows. Use Dependabot to maintain existing entries and gh actions-lock --verify to check for stale lockfiles. Evaluate mode is only on GitHub Enterprise Cloud; activate enforcement only after all targeted workflows are covered and lockfiles can stay current.

Sources