Install the gh-actions-lock extension, run it from the repository root, review the full diff, and commit. The lockfile records the exact commit for every action your workflows use, so a moved tag cannot swap code under you. GitHub marks this feature as public preview, so expect details to change.
Why a copied workflow needs this
A starter workflow typically references actions by version tag. A tag is a pointer, and GitHub's secure use guide says a tag can be moved or deleted if a bad actor gains access to the repository storing the action. Pinning to a full length commit SHA helps, and GitHub now calls a lockfile the strongest protection, since it records the exact commit for every action, including transitive dependencies, and verifies the identity of each source repository at run time.
The same guide says a lockfile supersedes SHA pinning for repositories that adopt it.
The steps, as GitHub documents them
- Check your references. Make sure each
usesline points at a supported, current version. The lockfile pins what the reference resolves to today, so lock the version you actually want. - Enable Dependabot first. GitHub recommends letting Dependabot manage action dependencies before you create the lockfile.
- Install the extension. With the GitHub CLI installed, run
gh extension install github/gh-actions-lock. - Generate the lockfile. From the repository root run
gh actions-lock. It scans every workflow under.github/workflows, pins each resolvable action to a commit SHA, and writes the lockfile. You can pass one workflow path to onboard a single file. - Review the whole diff. The extension changes more than the lockfile. It rewrites
usesreferences to the specific version it resolved, so a reference likev3can becomev3.1.0without changing the commit it points to. - Commit through a pull request.
Things that can surprise you
- Allowlists. GitHub says that once a workflow is onboarded, an allowlist is checked against locked commit SHAs. Entries pinned to a tag no longer match. Use a wildcard or the full commit SHA instead.
- Local actions. References like
./pathare rewritten to a form that always resolves to the running commit, so they need no lockfile entry. - Reusable workflows. Their dependencies are covered by the lockfile in the repository where the reusable workflow is defined. GitHub suggests onboarding shared workflow repositories first.
Keeping it current
Re-run the tool whenever you add a workflow with uses dependencies or change the dependencies in an existing one. When Dependabot opens a version update for an onboarded workflow, GitHub says it regenerates the matching lockfile entry in the same pull request. Dependabot will not onboard a workflow for you.
Reviewing lockfile changes
Treat them as dependency changes:
| Change | What it means | Action |
|---|---|---|
| New commit for an action | That is the code your workflow will run | Review like a version bump |
| Changed owner or repository ID | The repository behind the name is not the one you locked | Investigate before merging |
| Tag moved upstream | The reference now points elsewhere | Check upstream history, then relock only if the move was legitimate |
Never edit the lockfile by hand. If it looks wrong, fix the workflow files and regenerate.
Try it yourself
Click through it at your own pace, or open it full screen. Notice how a dependency inventory lists exactly what versions are in use. A lockfile gives your pipeline the same kind of record.
Quick check
Is a lockfile available on every plan?
GitHub's page lists the feature for people with write access and mentions GitHub Enterprise Cloud, and says it is in public preview. Check current availability before you plan around it.
If I use a lockfile, do I still need to read the action source?
Yes. A lockfile makes sure you run the code you reviewed. It does not review it for you.
Sources
- Locking action dependencies in a repository's workflows, GitHub Docs
- Secure use reference, GitHub Docs
Last reviewed: 19 October 2026.
