action-dist-verify

Rebuilds a GitHub Action's dist/ from the commit its uses: line pins to, and diffs the rebuild against what is committed.

import { verifyPaths } from 'action-dist-verify';

const report = await verifyPaths(['.']);
for (const r of report.results) console.log(r.status, r.uses, r.reason);
process.exit(report.exitCode);

Read "How it works" and "Limitations" before running this against anything you don't control: it executes the target action's install and build scripts on this machine.

SHA-pinning a uses: reference verifies you get the commit you asked for. It does not verify that the code which actually runs, almost always the committed dist/index.js named by runs.main in action.yml, corresponds to the src/ a reviewer looked at. The compromise of tj-actions/changed-files (CVE-2025-30066, March 2025) put its payload directly in the committed dist/; src/ stayed clean, and every consumer pinned by SHA still ran the payload.

Checked before writing this: zizmor, actionlint, and OpenSSF Scorecard lint workflow syntax and usage patterns; none of them rebuild an action and diff the result. The closest prior art, ericcornelissen/reproducing-actions, is a curated dashboard that rebuilds 56 chosen actions on a schedule and publishes pass/fail; it does not take an arbitrary repository's workflows as input.

Measured: ADV_NETWORK_TESTS=1 node --test test/network.test.ts, against actions/checkout@v4.2.2 (resolves to 11bd71901bbe5b1630ceea73d27597364c9af683):

{
  "uses": "actions/checkout@v4.2.2",
  "owner": "actions",
  "repo": "checkout",
  "resolvedSha": "11bd71901bbe5b1630ceea73d27597364c9af683",
  "runsUsing": "node20",
  "packageManager": "npm",
  "buildScript": "build",
  "status": "reproducible",
  "reason": "rebuilt dist is byte-identical to the committed dist"
}

npm ci --ignore-scripts && npm run build on Node 24 reproduces the committed dist/index.js exactly, matching the SHA1 (148b23ec6b39c2f4df4ebc18b69d0227dcc28fb2) established by hand before writing this tool. Full results from the same run, including two of the dashboard's currently-failing actions tried for real, are in "Development".

npm install --save-dev action-dist-verify

Requires Node >= 20.6, git on PATH, and whichever of npm, pnpm, or yarn the target action's lockfile specifies.

npx action-dist-verify              # scans ./.github/workflows
npx action-dist-verify path/to/repo

npx action-dist-verify .github/workflows/ci.yml

npx action-dist-verify --json . > report.json

import { verifyPaths } from 'action-dist-verify';

const report = await verifyPaths(['.'], { ignoreScripts: true });
const mismatches = report.results.filter((r) => r.status === 'mismatch');

action-dist-verify [path-to-repo-or-workflow-files...]

Exit codes:

verifyPaths(paths: string[], options?: VerifyOptions): Promise<VerifyReport>

Verifies every uses: reference reachable from paths (directories, or individual workflow/action.yml files). paths defaults to ['.'] when empty.

VerifyReport: { results: ActionResult[], exitCode: 0 | 1 | 2 }.

ActionResult.status:

Other exports: classifyUses(raw: string), parseGithubUses(raw: string), findWorkflowFiles(root: string), findAllUsesRefs(root: string), parseUsesFromFile(file: string), isFullSha(ref: string), lsRemoteSha(repoUrl: string, ref: string), shallowCheckout(repoUrl: string, sha: string, destDir: string), detectPackageManager(dir: string), findBuildScript(dir: string). Types: UsesRef, UsesKind, ActionStatus, MismatchFile, ToolchainInfo, PackageManager, ActionResult, VerifyOptions, VerifyReport.

For every uses: in .github/workflows/*.y{a,}ml, and in a root action.yml/action.yaml when the scanned path is itself a composite action:

1. Parse the reference with the yaml npm package (the only runtime dependency). Workflow YAML uses flow mappings, both quote styles, and block scalars for uses:; a line-oriented regex parses enough of that wrong to be unsafe for a security tool. ./local and docker:// references are not-applicable. A uses: built from an expression or matrix variable (${{ ... }}) is could-not-analyse.
2. Resolve the ref to a commit with git ls-remote, and record whether the workflow already pinned a full 40-hex SHA or a mutable tag/branch.
3. Fetch that one commit, shallowly where the remote allows it, and read runs.using from action.yml/action.yaml. Only node* actions proceed to rebuild; composite and docker actions are not-applicable.
4. Detect the package manager from whichever lockfile is present (ambiguous or missing is could-not-analyse, never a guess), install with --ignore-scripts, then run whichever of build, package, bundle, or all is defined as an npm script. More than one of those defined is could-not-analyse.
5. Compare the rebuilt files against the committed ones, by content hash, under the directory that runs.main (and pre/post) point into.

Every result records toolchain.nodeVersionUsed next to toolchain.declaredNodeVersion (from package.json#engines.node, .nvmrc, or .node-version, in that order), when the action declares one. A mismatch where these disagree is worth checking before assuming tampering: some bundlers produce version-dependent output.

• Does not verify dependency integrity beyond the lockfile. If a transitive dependency's own published dist/ is malicious, and the lockfile pins to that version, this tool rebuilds the malicious code and reports it reproducible, because it is reproducible from that source.
• A mismatch result never means "malicious." It cannot distinguish tampering from an unpinned build-time dependency, a nondeterministic bundler, or toolchain drift. It is reported as "dist does not match a rebuild from source," and nothing stronger.
• Does not automatically re-run a build under the declared Node version to separate toolchain drift from a real mismatch, even though it records enough (toolchain.nodeVersionUsed vs. .declaredNodeVersion) to do that by hand. Automating it, for example via npx -p node@<v>, needs its own trust boundary and is left out of this version.
• docker:// and composite actions are out of scope: there is no dist/ to rebuild for either.
• Runs the target action's install and build scripts on the machine invoking this tool. Run it in a disposable CI job or container. --ignore-scripts (the default) skips preinstall/postinstall hooks; it does not sandbox the build script itself, so a malicious build script in the target repository runs with this process's permissions.
• No retry or backoff around git ls-remote or fetch; a failed network call is reported as could-not-analyse.

Tested on Node 24.20.0 (node --test "test/*.test.ts", type-stripped, no build step) and against the built dist/ on the same Node version (test/smoke.mjs). CI (.github/workflows/test.yml) runs the smoke suite against Node 20.6, 22, and 24, but that matrix has not been run outside CI as part of this work.

pnpm and yarn support is implemented and was exercised for real against live actions (see "Development"), but is not covered by the offline fixture suite, which uses npm only: a pnpm/yarn fixture needs those binaries (via corepack) available in every environment the test suite runs in, which is not guaranteed.

node --test "test/*.test.ts"                        # offline: parser + fixture git repos
ADV_NETWORK_TESTS=1 node --test test/network.test.ts # real GitHub + real installs, opt in
npm run build && node --test test/smoke.mjs          # against the built dist/

The offline suite builds small local git repositories as fixtures (a real git init/commit, cloned by the tool via a local filesystem path): a reproducible node action, the same action with one line injected only into the committed dist/ (mismatch, exit 1), a composite action (not-applicable), and a build script that always fails (could-not-build, exit 2), plus workflow-parsing edge cases: subpaths, docker://, ./local, single- and double-quoted refs, and ${{ matrix.x }} expressions in uses:.

The network suite hits real GitHub and real npm/pnpm/yarn registries; it is skipped by default with an explicit message unless ADV_NETWORK_TESTS=1 is set. Real results from one run:

ncipollo/release-action and SonarSource/sonarqube-scan-action are both listed as currently failing by ericcornelissen/reproducing-actions. Both fail this tool's check too, for two different and identifiable reasons, neither of which is a dist/source mismatch.

MIT. See LICENSE.