Lock Your GitHub Actions

Table of Contents

GitHub Actions now supports workflow lockfiles.

Because GitHub Actions are fetched from Git, the previous advice was to pin to a full SHA instead of a tag. This is because tags are mutable and susceptible to supply-chain attacks where an attacker points a previously safe tag at malicious code.

For example, an old workflow looks like:

name: Lint on: [push, pull_request, workflow_dispatch] permissions: {} env: FORCE_COLOR: 1 RUFF_OUTPUT_FORMAT: github jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - uses: j178/prek-action@44924fe9ef4a6f88253c4b6b1bf11c689d3ce53d # v3.1.0 

Here’s how I set up lockfiles.

Install #

Install the gh-actions-lock extension to the gh CLI:

$ gh extension install github/gh-actions-lock ✓ Installed extension github/gh-actions-lock 

Lock ’em #

In your repo, run:

$ gh actions-lock ✓ All 1 workflows valid 

The workflow now uses vX.Y.Z tags and looks like this:

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 946971c..3503607 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -13,7 +13,7 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/[email protected] with: persist-credentials: false - - uses: j178/prek-action@44924fe9ef4a6f88253c4b6b1bf11c689d3ce53d # v3.1.0 + - uses: j178/[email protected] 

And it generates a lockfile at .github/workflows/actions.lock:

# 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/lint.yml': - 'actions/[email protected]' - 'j178/[email protected]' dependencies: 'actions/[email protected]': ref: 'v7.0.1' commit: 'sha1-3d3c42e5aac5ba805825da76410c181273ba90b1' owner_id: 44036562 repo_id: 197814629 'j178/[email protected]': ref: 'v3.1.0' commit: 'sha1-44924fe9ef4a6f88253c4b6b1bf11c689d3ce53d' owner_id: 10510431 repo_id: 1052387486 

Commit modified workflows and the new lockfile.

Renovate and Dependabot #

Good news, both already support lockfiles! Your periodic updates will also update the lockfile. Remember to use cooldowns.

Validate #

GitHub also recommends verifying lockfiles in CI to ensure it’s up-to-date and not corrupt.

They suggest copying this verify-lockfile.yml into your repo. I decided to put it into my existing lint workflow, but in its own job so it runs independently and in parallel:

name: Lint on: [push, pull_request, workflow_dispatch] permissions: {} env: FORCE_COLOR: 1 RUFF_OUTPUT_FORMAT: github jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/[email protected] with: persist-credentials: false - uses: j178/[email protected] # Fails when .github/workflows/actions.lock is out of sync with the # workflows or a locked pin no longer verifies upstream. lockfile: runs-on: ubuntu-slim env: GH_TOKEN: ${{ github.token }} steps: - uses: actions/[email protected] with: persist-credentials: false - run: gh extension install github/gh-actions-lock --pin v0.4.1 - run: gh actions-lock --verify 

Note I’m using the lightweight ubuntu-slim runner here. Also, it’s pinning to v0.4.1; we’ll have to update that at some point or figure out a way to automate it. That’s for another time.

Don’t forget that we just modified the actions in a workflow, so need to relock with gh actions-lock. Nothing actually changes if adding to lint.yml because it’s already locking actions/checkout. But if you created a new file like verify-lockfile.yml, you’ll need to relock for that. The CI will let you know.

zizmor #

zizmor is a security linter for GitHub Actions and strongly recommended. If you don’t use it, please do.

Versions before v1.32.0 tell you to hash-pin actions, and v1.32.0 is the first to support lockfiles.

I use zizmor in prek, so add/update zizmor in .pre-commit-config.yaml:

 - repo: https://github.com/zizmorcore/zizmor-pre-commit rev: v1.32.0 hooks: - id: zizmor 

Locked! #

OK, commit and push!

Examples #

• python-pillow/Pillow#10428
• python/release-tools#477
• python/miss-islington#758
• python/cpython#161811

---

Header photo: Slaymaker Barry Co. Sprocket Locks in The Bearings (vol. XII no. 23, 2nd January 1896) in the Smithsonian Libraries and Archives, with no known copyright restrictions.