Your CI pipeline needs a lockfile, too
Lockfiles might be familiar to you if you’ve ever worked with package managers like npm or Yarn (for the JavaScript ecosystem) or Composer (for the PHP ecosystem). A lockfile, as the name suggests, is a data file generated by these package managers that “locks in” or, in other words, records exact dependency versions, cryptographic hashes, or resource-access states.
And since lockfiles pin the exact versions and transitive dependencies of libraries, it guarantees that every developer or CI/CD server installs the exact same code. The workflow becomes reproducible. And so, we are sorted when it comes to making the workflow consistent on the application or its build level.
However, one important part of the software supply chain has largely lacked this capability: CI/CD workflows. That changed recently with the general availability of workflow dependency lockfiles for GitHub Actions.
The GitHub Actions workflow that builds, tests, and deploys applications can itself depend on executable code maintained by other repositories.
Consider this workflow step.
- uses: actions/checkout@v4
The reference here is readable and convenient. However, a tag can be moved to point to different code, meaning the workflow could execute code different from what its author originally reviewed.
One solution is to pin the action directly to a full-length commit SHA. That makes the reference immutable, but it also makes workflow files harder to read and maintain.
- uses: actions/checkout@<FULL_40_CHARACTER_COMMIT_SHA>
And this is where the actions.lock file comes into the picture.
GitHub’s workflow dependency lockfiles offer another approach: keep readable references in the workflow YAML while recording the exact commits in a separate actions.lock file.
For this, you first need to install the GitHub Actions lockfile extension like so.
gh extension install github/gh-actions-lock
Then the actions lockfile can be generated like so.
gh actions-lock
This will generate a .github/workflows/actions.lock file that would roughly look like this.
# This file is machine-generated by `gh actions-lock`.
# Do not edit by hand; run `gh actions-lock` to update.
# Docs: https://gh.io/actions-lockfile
version: 'v0.0.3'
workflows:
'.github/workflows/ci.yml':
- 'octo-org/[email protected]'
dependencies:
'octo-org/[email protected]':
ref: 'v3.1.0'
commit: 'sha1-...'
owner_id: 44036562
repo_id: 197814629
As you can tell, we have the workflow key that records the usual dependencies but the interesting bit here lies in the dependencies key and it records which commit each of those references resolves to using ref, commit, owner_id, and so on.
GitHub Actions uses the lockfile to resolve action references to their recorded commits. When Dependabot updates a supported action dependency, it can also update the corresponding lockfile entry, keeping the two in sync.
With the actions.lock file, your CI/CD pipeline gains another layer of dependency consistency. But locking dependencies doesn’t automatically make them trustworthy. It doesn’t protect against malicious code that was already present when the lockfile was generated, nor does it lock every other build input, such as runner images or arbitrary action inputs.
You still need to review your dependencies, keep permissions to a minimum, and secure the pipeline as a whole.
So, the bottom line?
Developers often think about dependency security in terms of the packages shipped with their application. But CI/CD workflows also execute third-party code, sometimes with access to source code, repository permissions, and deployment credentials. That makes the pipeline an important part of the software supply chain.
Remember, your application isn’t the only thing with dependencies. Your build pipeline has them, too.
And that’s why workflow dependency lockfiles are a welcome addition to the GitHub Actions ecosystem.
👋 Hi there! This is Amit, again. I write articles about all things web development. If you enjoy my work (the articles, the open-source projects, my general demeanour... anything really), consider leaving a tip & supporting the site. Your support is incredibly appreciated!
