actions-lockfile-generator

Pin GitHub Action tags to full commit SHAs and generate auditable lockfiles to prevent supply chain attacks.

GitHub Action tags like uses: actions/checkout@v4 are mutable. A malicious actor who gains access to a repository can move a tag to a compromised commit, potentially executing arbitrary code in your CI environment (SolarWinds-style).

actions-lockfile-generator automatically resolves your action tags to immutable full commit SHAs, updates your workflow files, and maintains a reproducible actions-lock.json.

Features

• Automatic Pinning — Scans .github/workflows/*.yml, resolves tags to current full SHAs, and updates them in-place.
• Reproducible Lockfile — Generates actions-lock.json for auditing and cross-workflow consistency.
• Validation — Ensures every SHA actually exists via the GitHub API before writing.
• Workflow Integrity — Validates workflow YAML structure before and after transformation to prevent breakage.
• Flexible Modes — Supports scan (report only), pin (update files), and enforce (fail if unpinned actions exist).
• PR Reports — Posts a detailed breakdown of pinned and unpinned actions to your PR summary.

Example Transformation

Before

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v3

After

steps:
  - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
  - uses: actions/setup-node@1a4442cacd436585916779262731d1f68b4d3696 # v3

Quick Start

Add this to your CI to automatically detect unpinned actions:

- uses: ollieb89/actions-lockfile-generator@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    mode: scan

Configuration

Create actions-lockfile.config.yml for custom policies:

mode: strict
allowed-orgs:
  - actions
  - github
on-unpinned: fail
ignore:
  - .github/workflows/local-only.yml

Inputs

Input	Description	Default
github-token	Token for resolving SHAs via GitHub API	${{ github.token }}
workflow-dir	Directory containing workflow files	.github/workflows
mode	scan, pin, or enforce	scan
config-path	Path to config file	actions-lockfile.config.yml
output-file	Path for the generated lockfile	actions-lock.json

CLI Usage

Run via npx without installation:

# Scan and report
npx actions-lockfile-generator --mode scan --token $GITHUB_TOKEN

# Pin actions in workflow files
npx actions-lockfile-generator --mode pin --token $GITHUB_TOKEN

Security Narrative

"Mutable tags are a massive blind spot in CI/CD security. Compromising a single action used by thousands of repos allows attackers to inject malicious code at scale. Pinning to full commit SHAs is the primary defense-in-depth recommendation from GitHub and the OpenSSF. actions-lockfile-generator makes this defense effortless."

License

MIT — see LICENSE

---

Part of the AI DevOps Actions suite

This action is one of five tools that form the AI DevOps Actions suite — the CI/CD layer for AI-native development.

Action	Purpose
ai-pr-guardian	Gate low-quality and AI-generated PRs
llm-cost-tracker	Track AI API costs in CI, alert on overruns
mcp-server-tester	Validate MCP servers: health, compliance, discovery
actions-lockfile-generator	Pin Actions to SHA, prevent supply chain attacks
agent-skill-validator	Lint and validate agent skill repos

→ View the full suite and pipeline example