GitHub Actions workflow lockfiles close a specific CI security gap. They freeze the exact commit behind each action, so a tag or branch can’t quietly swap in different code later. GitHub shipped the feature as a public preview on October 14, 2026. For teams still pinning actions by hand, it closes a risk attackers have already exploited.
What a Workflow Lockfile Pins Down
A workflow lockfile is a file that .github/workflows/actions.lock that records the exact commit each action in your workflow resolves to. Your workflow file still references actions the normal way, by tag or branch. However, GitHub Actions executes the commit recorded in the lockfile instead of whatever that tag currently points to. The lockfile also tracks transitive dependencies, meaning actions that your actions call internally.
GitHub generates and maintains the file with a CLI extension called gh actions-lock. You should never edit the lockfile by hand. Running the extension again regenerates it and surfaces changes as a reviewable diff, similar to how package-lock.json works for npm.
Why GitHub Introduced Workflow Lockfiles
Most workflows reference actions by a moving target, like @v3 or @main. That reference can point to different code tomorrow than it does today. If a maintainer’s account gets compromised, an attacker can move the tag to malicious code. Every workflow that trusts that tag then inherits the breach. Nothing changes in your own repository to warn you.
This is not theoretical. In March 2025, attackers compromised the tag on reviewdog/action-setup. This action is a transitive dependency of tj-actions/changed-files, used in over 23,000 repositories. The breach, tracked as CVE-2025-30066, dumped CI/CD secrets straight into build logs. Security spending has followed incidents like this. The DevSecOps market keeps growing as teams push security earlier into the build and release process. Workflow lockfiles extend that shift further, directly into CI configuration.
How GitHub Actions Workflow Lockfiles Work
Each lockfile entry stores three things. It records the reference your workflow uses and the commit that reference resolved to. The entry also stores the numeric owner and repository IDs of the source. GitHub Actions checks that repository identity at runtime. The check catches a specific attack. Someone deletes an action repository and recreates it under the same name with malicious code.
Onboarding happens workflow by workflow, not all at once across a repository. Once you onboard a workflow, every dependency it uses must appear in the lockfile, with no exceptions. GitHub’s public preview announcement says teams can also run a verification check in CI. This check confirms the lockfile is current without modifying any files. That lets you fail a build automatically if someone adds a new, unlocked dependency.
Dependabot plugs directly into this system. When Dependabot opens a version update for an action in an onboarded workflow, it regenerates the matching lockfile entry. That entry lands in the same pull request. Reviewers then see both the version bump and the new commit hash together, in one diff.
Setting Up a Workflow Lockfile
Getting started takes a few steps. First, install the gh actions-lock extension from its GitHub repository. Next, run it against workflows that handle secrets, deploy to production, or trigger on pull requests from forks. Review the generated lockfile and the resulting diff to your workflow files, then commit both together.
Enterprise, organization, and repository administrators can go further with a Require Lockfile policy. This mirrors how many teams already standardize their enterprise development tools and approval processes across repositories. Once that policy is active, any onboarded workflow without a complete, current lockfile fails before it runs. It no longer gets flagged only after the fact.
Workflow Lockfiles vs Manual SHA Pinning
GitHub’s older guidance told teams to pin third-party actions to full commit SHAs by hand instead of tags. That approach still works, but it has real downsides. Workflow files become hard to read once every action reference is a 40-character hash. Manual pinning also misses transitive dependencies. An action you trust can still pull in an unpinned dependency of its own.
Lockfiles solve both problems at once. Your workflow files stay readable, using normal tags or branch names. Meanwhile, the lockfile separately tracks the commits that actually run, including everything those actions depend on. For repositories that adopt a lockfile, GitHub says manual SHA pinning is no longer necessary.
Common Mistakes When Adopting Workflow Lockfiles
Teams sometimes treat a locked dependency as safe. It is not. Locking only fixes a dependency to a specific, known commit. It does not review that commit for vulnerabilities or malicious code. You still need to vet an action before you lock it in.
Another common mistake is onboarding every workflow at once without reviewing the diffs. The lockfile exists precisely so changes stay visible and reviewable. Skipping that review defeats the purpose, since nobody actually confirms what commit got locked.
Finally, some teams forget the feature is in public preview, meaning behavior and plan availability may still change. Treat it as a strong addition to a security posture, not a finished, permanent standard.
Key Takeaways
- Workflow lockfiles pin every GitHub Actions dependency to a specific commit, not a movable tag or branch.
- The
gh actions-lockCLI extension generates the lockfile at.github/workflows/actions.lock. - GitHub launched the public preview on October 14, 2026, for Enterprise Cloud, Team, and Free plans.
- Dependabot automatically updates lockfile entries alongside version-bump pull requests.
- Locking a dependency does not verify it is safe; you still have to review it.
Frequently Asked Questions About GitHub Actions Workflow Lockfiles
What Is a GitHub Actions Workflow Lockfile?
It is a file that records the exact commit each action and reusable workflow resolves to. A moved tag or branch cannot silently change what code runs.
Where Is the Lockfile Stored?
GitHub stores it at .github/workflows/actions.lock in the repository, alongside the workflow files it protects.
Do I Need to Edit the Lockfile Manually?
No. You generate and update it with the gh actions-lock CLI extension. Manual editing is not supported.
Does a Lockfile Replace Reviewing My Actions?
No. Locking a dependency fixes it to a known commit, but it does not evaluate whether that commit is safe. You still need to review new or updated actions yourself.
Can I Require Lockfiles Across My Whole Organization?
Yes. Enterprise, organization, and repository administrators can turn on a Require Lockfile policy. It blocks onboarded workflows from running without a current lockfile.
Is This Feature Available Now?
Yes, in public preview as of October 14, 2026, on GitHub Enterprise Cloud, GitHub Enterprise Cloud with data residency, Team, and Free plans.
Final Thoughts
The real decision here is not whether lockfiles sound useful. It is whether your current workflows trust a tag you haven’t rechecked since you added it. The tj-actions and reviewdog incidents show how fast attackers can abuse that trust. If any CI pipeline deploys to production or touches secrets, start there. Onboard it, then read every diff before you merge it. That habit costs little next to a leaked secret.
Photo by RealToughCandy.com: Pexels
Deanna Ritchie is a managing editor at DevX. She has a degree in English Literature. She has written 2000+ articles on getting out of debt and mastering your finances. She has edited over 60,000 articles in her life. She has a passion for helping writers inspire others through their words. Deanna has also been an editor at Entrepreneur Magazine and ReadWrite.
