actionpin

A version tag is a promise anyone can break. A commit SHA is not.

Quickstart

npx @reneturcios/actionpin audit

GitHub Actions are executable supply chain. When a workflow says uses: actions/checkout@v4, that tag can move. When a third-party action tag moves to a compromised commit, every workflow that trusts the tag runs the new code with that workflow's tokens. Pinning to a full 40-character commit SHA is the standard defense, and almost nobody does it consistently, because doing it by hand across every workflow is tedious and easy to get wrong.

actionpin audits every workflow in a repo, reports exactly which actions are pinned and which are not, and can rewrite the unpinned ones to SHAs for you, keeping the original tag as a comment so the pin stays readable.

Why this exists

GitHub Actions are the second largest confirmed open source supply-chain attack surface of the last year, behind only npm. Maintainer accounts and action tags have been hijacked before, and a mutable tag means the code your CI runs today is not guaranteed to be the code you reviewed. The fix is known and boring: pin to a SHA. actionpin makes the boring fix one command, and makes the audit callable by agents through MCP so it can run inside contribution and release workflows, not just by hand.

What it checks

For every uses: line in .github/workflows/*.yml and *.yaml:

Owner types: official for actions owned by actions or github, third-party for everyone else, docker for docker:// container actions, and local for local paths.

Verdict rules:

• PINNED: every non-local action is pinned to a full SHA. Exit code 0.
• EXPOSED: at least one third-party or container action uses a mutable tag or a branch. Exit code 1.
• PARTIAL: only official actions are unpinned. Exit code 1.
• Usage errors exit with code 2.

Fix mode resolves a tag or branch to its commit SHA through the GitHub API and rewrites the line to owner/repo@<sha> # <original ref>, preserving indentation and all other content. Files are edited line-wise; YAML is never parsed and re-emitted, so formatting survives. If a ref cannot be resolved, its line is left unchanged and the failure is reported. Docker image refs are reported but not rewritten; pin those by digest.

Usage

CLI

# Audit the current repo
npx @reneturcios/actionpin audit

# Audit another path, machine readable
npx @reneturcios/actionpin audit ~/src/my-repo --json

# Audit every repo checkout under an org root and report pin drift
# (the same action used at different refs in different repos)
npx @reneturcios/actionpin org ~/src/my-org --json

# Preview the pinning plan without writing
npx @reneturcios/actionpin fix --dry-run

# Pin everything resolvable, in place
npx @reneturcios/actionpin fix

Example output:

actionpin audit .: EXPOSED
  workflows: 2, actions: 6, pinned: 1, mutable: 4, branch: 1, local: 0
  [PINNED] .github/workflows/ci.yml:12 actions/checkout@0123456789abcdef0123456789abcdef01234567 (official)
  [MUTABLE] .github/workflows/ci.yml:13 actions/setup-node@v4 (official)
  [MUTABLE] .github/workflows/publish.yml:20 docker/b

... [View full README on GitHub](https://github.com/cloudcorprecords/actionpin#readme)