GitHub Actions workflow lockfiles are GA: what actions.lock locks and what it doesn't prove about release swaps
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:
- Direct and transitive Actions: the lockfile pins the Actions your workflow calls, including Actions those Actions use.
- Source identity: each dependency records its reference, commit,
owner_id, andrepo_id. GitHub checks that the repository behind the name is still the one you locked. - Reachability: the commit must remain reachable from its recorded branch or tag in the Action's own repository. A commit found only in a fork, or no longer reachable from that reference, is rejected at run time.
- Not reusable-workflow calls:
jobs.<job_id>.usesis not pinned by this lockfile. Pin those calls to full commit SHAs separately. Their Action dependencies belong in the lockfile of the repository where the reusable workflow is defined. - Not every build input: input parameters, secrets, and the runner image are outside the lockfile's scope.
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).
- Published files are another layer. A locked pipeline can publish to an unlocked release. A later attacker with release-write access can still replace those assets if immutable releases are not enabled. See Can this GitHub release be swapped? and lessons from release-swap incidents.
- A lockfile is not artifact attestation. It does not attest the contents of PyPI wheels, container images, or release tarballs. The LiteLLM clean-tag, poisoned-release case shows why checking source references alone is not the same as checking the shipped artifact.
- Tokens still need protection. A lockfile does not revoke stolen tokens or stop them from creating or editing releases. Our GhostAction guide explains the release-write risk, without claiming that GhostAction swapped releases.
- Unonboarded workflows still follow their references. Locking one workflow does not protect another that is not onboarded. Even in a locked workflow, a malicious commit remains malicious if you choose to lock it. See re-enabled Actions with compromised tags.
- Dangerous triggers are a separate control. Dependency locking does not make executing untrusted pull request code with secrets safe. See pull_request_target blocked by default.
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.