Usage

This guide walks through the recommended workflow for integrating gh-actions-lockfile into your project.

Step 1: Generate Your Initial Lockfile

Run the action in generate mode to create your lockfile:

name: Generate Lockfile
on: workflow_dispatch

jobs:
  generate:
    runs-on: ubuntu-latest
    permissions:
      # Gives the default GITHUB_TOKEN write permission to commit and push the
      # added or changed files to the repository.
      contents: write

    steps:
      - uses: actions/checkout@v6

      - uses: gjtorikian/gh-actions-lockfile@v1
        with:
          mode: generate

      - name: Commit lockfile
        # Commit the changed lockfile back to the repository
        uses: stefanzweifel/git-auto-commit-action@v7
        # or, something like
        # run: |
        #   git add .github/actions.lock.json
        #   git commit -m "Add actions lockfile"
        #   git push

Or locally with the CLI:

npx gh-actions-lockfile generate
git add .github/actions.lock.json
git commit -m "Add actions lockfile"

export GITHUB_TOKEN=ghp_your_token_here

You really only need to generate this initial lockfile once, so choose whichever version makes the most sense.

Step 2: Verify on Every Action Run

Add verification to your CI workflow. If verification fails, the lockfile is automatically regenerated and committed to the PR:

name: Verify Actions
# change this to whichever events matter to you
on: [pull_request]

permissions:
  pull-requests: write

jobs:
  verify-actions:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: gjtorikian/gh-actions-lockfile@v1
        with:
          mode: verify

  update-lockfile:
    needs: verify-actions
    if: failure()
    runs-on: ubuntu-latest
    permissions:
      # Gives the default GITHUB_TOKEN write permission to commit and push the
      # added or changed files to the repository.
      contents: write
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.head_ref }}

      - uses: gjtorikian/gh-actions-lockfile@v1
        with:
          mode: generate

      - uses: stefanzweifel/git-auto-commit-action@v7
        with:
          commit_message: "Update actions lockfile"
          file_pattern: ".github/actions.lock.json"

When you update an action version (e.g., actions/checkout@v4 to @v5), or if the action ref changes outside of your control, the verify job will fail, triggering the update job to regenerate and commit the lockfile to your PR automatically.

Manual Updates

If you prefer to update the lockfile locally instead of auto-committing via GitHub Actions, you can:

1. Make your workflow changes
2. Regenerate the lockfile:

   npx gh-actions-lockfile generate

3. Review the lockfile diff to confirm expected changes
4. Commit both the workflow and lockfile changes together

When Verification Fails Unexpectedly

If verify fails, but you didn’t change any actions, investigate:

• New dependency detected: A composite action you use added a new transitive dependency
• SHA mismatch: An upstream maintainer force-pushed or retagged a version (this is a potential supply chain concern)
• Integrity mismatch: The tarball content has changed for the same SHA (rare, but a serious supply chain concern)
• Missing action: An action was removed from your workflow but is still in the lockfile

For unexpected changes, review the upstream action’s commit history before regenerating the lockfile.

Security Features

SHA Verification

When you run verify, the tool checks that all locked action refs still resolve to the same commit SHAs. This detects if an upstream maintainer has re-pointed a tag to a different commit.

To skip SHA verification, use --skip-sha.

Integrity Verification

The verify command also:

1. Re-downloads each action’s tarball from GitHub
2. Computes the SHA256 hash of the tarball
3. Compares it against the stored integrity hash in your lockfile

If any hash mismatches, verification fails. To skip integrity checking (e.g., for faster CI runs), use --skip-integrity.

Security Advisory Checking

By default, the verify command checks your locked actions against the GitHub Advisory Database for known vulnerabilities. When vulnerabilities are found, they are reported as warnings (not failures).

To disable advisory checking, use --skip-advisories.

SHA-Only Mode

For maximum security, you can enforce that all action references use full 40-character commit SHAs instead of tags:

npx gh-actions-lockfile generate --require-sha

This fails if any workflow uses a tag like @v4 instead of a full SHA.

Action Inputs

When using the GitHub Action, you can configure:

PR Comments

When comment is enabled (the default) and verification fails in a pull request, the action automatically posts a comment detailing what changed. This makes it easy to review lockfile mismatches directly in the PR without checking the action logs.