Europe/Paris
Posts

GitHub Actions lockfiles: readable tags in your workflows, locked commits at run time

November 16, 2026 · 7 min de lecture
In a GitHub Actions workflow, uses: actions/checkout@v5 does not point to frozen code: a Git tag can be moved to another commit at any time, and your CI will run that new commit without a single change in your repository. Since October 28, 2026, GitHub offers a generally available answer that no longer forces you to choose between readability and safety: a lockfile for actions, .github/workflows/actions.lock. The risk is not theoretical. In March 2025, the tags of the tj-actions/changed-files action were pointed at a malicious commit that dumped runner (the machine executing the job) secrets into the logs: every repository referencing the action by tag ran that code. The usual defense is SHA pinning (referencing the action by the full hash of its commit, which cannot change):
Yaml
# the full commit SHA (40 hex characters), then the version as a comment
- uses: actions/checkout@<commit-sha> # v5.1.0
It works, with two flaws. The file becomes unreadable, and code review relies on a comment nobody checks. More importantly, the SHA only protects the first level: if the action is a composite action (an action that itself calls other actions), its own dependencies are still referenced by tag, in a repository you do not control. The lockfile borrows the idea of composer.lock: workflows keep readable references, and a generated file records the exact commit of every action, transitive dependencies included. The GitHub changelog sums it up: keep readable tags and branches while running the locked commits, even if those references move. Everything goes through a GitHub CLI extension, gh actions-lock. Take a standard test workflow:
Yaml
# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

jobs:
  tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
          coverage: none
      - run: composer install --no-progress --prefer-dist
      - run: vendor/bin/phpstan analyse --no-progress
      - run: vendor/bin/phpunit
Install the extension and generate the lockfile from the repository root:
Bash
gh extension install github/gh-actions-lock
gh actions-lock --version

# Lock every workflow in the repository
gh actions-lock

# Or a single workflow, for gradual adoption
gh actions-lock .github/workflows/ci.yml

git add .github/workflows/
git commit -m "ci: lock GitHub Actions dependencies"
As Yuji Nishimura shows on the Classmethod blog, the command does two things. It creates actions.lock, a generated YAML file you never edit by hand: a version key, a workflows key listing the actions each file uses, and a dependencies key mapping each reference to its ref (original tag), its commit, the repository's numeric IDs (owner_id, repo_id) and, for a composite action, its own uses. It also rewrites short references to full tags: in his test, actions/checkout@v5 becomes actions/checkout@v5.1.0. The --no-narrow option turns that rewrite off. From then on, an onboarded workflow (one listed in the lockfile) runs the recorded commit, even if the tag is moved later. And if someone adds an action without regenerating the lockfile, the run ends in startup_failure: no job starts. The catch with that startup_failure is how quiet it is. Yuji Nishimura notes in his second article that the broken run does not show up in the checks returned by gh pr checks; only the verify job does. So you need a dedicated job that checks the lockfile without modifying any file, modeled on the sample in the extension's repository:
Yaml
# .github/workflows/verify-actions-lock.yml
name: Verify actions lockfile

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Check actions.lock
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh extension install github/gh-actions-lock --pin v0.4.0
          gh actions-lock --verify
No paths filter: the job has to run on every pull request so it can become a required check (a required check that never runs blocks the merge). And the extension version is pinned (--pin installs a fixed release): the official sample installed v0.2.0, which Nishimura advises against because it lets through lockfiles missing composite action dependencies. Once this workflow exists, onboard it too with gh actions-lock. Locally, when --verify reports an unlocked action, the fix is two commands:
Bash
gh actions-lock .github/workflows/ci.yml
gh actions-lock --verify
A lockfile that never moves ends up pinning vulnerable versions. If Dependabot already watches your actions, there is nothing to add: according to the GitHub changelog, when it opens a version update for an action in an onboarded workflow, it regenerates the matching lockfile entry in the same pull request. It does not onboard new workflows, though: that remains a manual gh actions-lock.
Yaml
# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly
To follow a tag that has moved, you have to ask explicitly: gh actions-lock --relock. That is by design: a moved tag is exactly the attack scenario, so switching to the new commit must be a deliberate act, visible in a reviewed diff. Onboarding one workflow does not cover the next one. Enterprise, organization and repository administrators can turn on the "Require lockfile" policy: any workflow missing from the lockfile then fails with startup_failure, including workflows with no actions or already pinned by SHA. Nishimura notes that the policy was still labeled Preview on November 2, and points out a major limit: on private repositories of a Free account, it is not enforced. In that case he recommends combining mandatory SHA pinning (a separate setting, which is enforced there) with the --verify job, since a SHA-pinned workflow runs even when it is not onboarded. Another change from the same security push: starting December 2, 2026, GitHub will block pull_request_target events (a trigger that runs with the target repository's secrets, even for a PR coming from a fork) by default in public repositories (Free, Team and Enterprise Cloud), unless an Actions event policy (an organization or repository setting that allows or blocks triggers) explicitly allows them. Private and internal repositories are not affected, and neither is GitHub Enterprise Server. Until then, the rule runs in evaluate mode: runs go through with a warning, visible in Insights. GitHub also scheduled two test windows (brownouts), on November 9 and today, November 16, from 16:00 to 18:00 UTC, during which affected runs fail. If one of your open source projects relies on it, now is the time to check.
  • The lockfile does not cover everything. According to the summary Anna published on DEV, reusable workflows (called through jobs.<job>.uses) are not locked and still need SHA pinning, Docker images are not locked either (pin them by @sha256: digest, the hash of the image content), local ./ actions are not followed, and a tag moved back to an older commit of its own history is not detected. GitHub Enterprise Server is not supported.
  • Locking is not auditing. GitHub says it plainly: the lockfile protects against unexpected changes, not against a dependency that is already malicious when you lock it. Reviewing the action before the first gh actions-lock is still on you.
  • The --accept-moved option accepts a moved tag without complaint. It has no place in a script or an automated job, or the lockfile stops serving any purpose.
If you already have a CI that blocks merges on PHPStan and tests, as in my article on the Definition of Done, add verify-actions-lock to the required checks of the protected branch: it is the job that surfaces the startup_failure the PR does not show.
On this page
Book a call