Lock your GitHub Actions

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.