How to Configure Lockfiles in GitHub Actions to Protect Your Pipelines

A practical guide to implementing dependency lockfiles in GitHub Actions, the new GA feature that pins specific commits in your workflows.

Software engineering

GitHub has released workflow dependency lockfiles in GitHub Actions for general availability, just two weeks after entering public preview. This feature solves a known problem: when you use a reference like actions/checkout@v4, that tag can change without your repository being modified. An attacker who compromises an action can inject malicious code into your pipeline without leaving a trace in your code.

The traditional solution was to pin full commits with SHAs, but this reduces readability and doesn't cover transitive dependencies of composite actions. Lockfiles record the commits of both direct and transitive dependencies in a .github/workflows/actions.lock file, and the runner executes exactly those commits even if tags or branches change later.

What You Need

To implement lockfiles, you need access to GitHub Enterprise Cloud, Enterprise Cloud with data residency, Team plan, or Free plan. You will also need to install the gh actions-lock extension for the GitHub CLI, hosted in the gh-actions-lock repository. This tool generates and maintains the lockfile.

• GitHub CLI installed on your local machine
• Write permissions to the repository where you want to enable lockfiles
• Existing workflows you want to protect
• Dependabot configured if you want synchronized automatic updates

The lockfile intercepts references and enforces specific commits

Steps to Implement Lockfiles

1. Install the extension by running gh extension install github/gh-actions-lock in your terminal.
2. Navigate to the repository where you want to enable lockfiles and run gh actions-lock init to generate the .github/workflows/actions.lock file.
3. Review the dependencies listed in the lockfile before committing. GitHub explicitly warns that the lockfile guarantees you use the locked commits, but it does not determine if those commits are secure.
4. Add the lockfile to your repository with a normal commit and push.
5. Configure the verification mode in your CI by running gh actions-lock verify as a pipeline step to detect differences between workflows and the lockfile.

Adoption can be incremental. Once a workflow is configured, each dependency needs an entry in the lockfile. This allows migrating flow by flow instead of converting an entire organization at once. We recommend starting with high-privilege workflows like release or deployment workflows.

Tip When Dependabot opens a pull request to update an action in a configured workflow, it also automatically updates the corresponding lockfile entry. Both changes appear in the same PR, keeping the reference and the locked commit synchronized without additional configuration.

Governance Policies and Limitations

Enterprise, organization, or repository administrators can enable a "Require lockfile" policy to enforce adoption at the corresponding scope. Refer to the official lockfile documentation for detailed configuration instructions.

It's important to understand the limitations: the lockfile does not evaluate whether locked dependencies are trustworthy. The security value depends on the review that occurs when an entry is created or updated. In practice, the Dependabot pull request becomes the review point. Teams that auto-merge these updates without review could propagate malicious code directly into the lockfile.

Dependabot automatically synchronizes the lockfile in its pull requests

Comparison with Other Platforms

GitLab recommends manually pinning includes and components to commit SHAs, as well as pinning images to digests. After the incidents in March 2026, they introduced pipeline execution policies that block known attack patterns instead of creating a dependency manifest. Azure Pipelines follows the Microsoft Zero Trust guide which suggests SHA pinning and limiting Marketplace extensions.

Cross-platform tools like pinner and ActionSieve help pin references and detect missing pins, but they do not resolve transitive dependencies. This is precisely the gap that GitHub's lockfile design addresses, although none of these solutions judge whether a pinned dependency is trustworthy.

Opinion · My 12-month bet

My 12-month bet: GitLab and Azure Pipelines will have to respond with something equivalent. The problem of unresolved transitive dependencies is too obvious to ignore after the incidents of March 2026. GitHub has made the first move, giving them an advantage with teams that prioritize security over convenience.

That said, the weak link remains human: anyone who auto-merges Dependabot pull requests without reviewing them is propagating the same risk they are trying to mitigate. The tool helps, but it doesn't replace judgment.

Related articles from LaRebelión

How to Prepare Your Open Source Project for Anthropic's OSS ScannerGuide to Assessing Your GitHub Dependency in the Age of AgentsHow to Check What a Desktop App Installs on Your AI Agents

• Software engineering
• How to Test tsrs: The TypeScript Compiler in Rust
• Cloudflare's tsrs: A Guide to Evaluating the TypeScript to Rust Port

Original source: infoq.com

Article generated with AI.larebelion

Kernel · Technology Director · Spain

«Lockfiles are useful, but the real control remains the review before locking.»