danielroe.dev
[READ-ONLY] Mirror of https://github.com/danielroe/provenance-action. Fail CI when dependencies in your lockfile lose npm provenance or trusted publisher status
github-actions
provenance
security
trusted-publishing
4.7 kB
88 lines
1# `danielroe/provenance-action`
2
3Fail CI when dependencies in your lockfile lose npm provenance, trusted publisher or staged publishing status.
4
5> [!WARNING]
6> This action is under active development and is only one tool to assist in securing your dependencies.
7
8> [!NOTE]
9> **pnpm users:** As of [pnpm v10.21](https://github.com/pnpm/pnpm/releases/tag/v10.21.0), pnpm now has built-in support for `trustPolicy` in `.npmrc`, which provides native enforcement of provenance checks. If you're using pnpm v10.21 or later, you may not need this action. See the [pnpm documentation](https://pnpm.io/blog/releases/10.21#trust-policy) for more details.
10
11## ✨ Features
12- supports `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock` (v1 and v2+), `bun.lock`
13- handles transitives by comparing resolved versions
14- inline GitHub annotations at the lockfile line
15- JSON output and optional hard‑fail (default: on)
16- pure TypeScript, Node 24+
17
18👉 See it in action: [danielroe/provenance-action-test](https://github.com/danielroe/provenance-action-test)
19
20## 🚀 Quick start
21```yaml
22name: ci
23on:
24 pull_request:
25 branches:
26 - main
27 paths:
28 # Trigger a run only on PRs that change the lockfile
29 # (keep whichever is relevant and/or configure its path):
30 - pnpm-lock.yaml
31 - package-lock.json
32 - yarn.lock
33 - bun.lock
34
35permissions:
36 contents: read
37jobs:
38 check-provenance:
39 runs-on: ubuntu-latest
40 steps:
41 - uses: actions/checkout@v4
42 with:
43 fetch-depth: 0
44 - name: Check provenance downgrades
45 uses: danielroe/provenance-action@main
46 id: check
47 with:
48 fail-on-provenance-change: true # optional, default: false
49 # lockfile: pnpm-lock.yaml # optional
50 # base-ref: origin/main # optional, default: origin/main
51 # fail-on-downgrade: true # optional, default: true
52 - name: Print result
53 run: "echo 'Downgraded: ${{ steps.check.outputs.downgraded }}'"
54```
55
56## 🔧 Inputs
57- `lockfile` (optional): Path to the lockfile. Auto-detected if omitted.
58- `workspace-path` (optional): Path to workspace root. Default: `.`
59- `base-ref` (optional): Git ref to compare against. Default: `origin/main`.
60- `fail-on-downgrade` (optional): Controls failure behavior. Accepts `true`, `false`, `any`, or `only-provenance-loss`. Default: `true` (which is the same as `any`).
61- `fail-on-provenance-change` (optional): When `true`, fail on provenance repository/branch changes. Default: `false`.
62
63## 📤 Outputs
64- `downgraded`: JSON array of `{ name, from, to, downgradeType }` for detected downgrades. `downgradeType` is `provenance`, `trusted_publisher` or `staged_publish`.
65- `changed`: JSON array of provenance change events `{ name, from, to, type, previousRepository?, newRepository?, previousBranch?, newBranch? }`.
66
67## 🧠 How it works
681. Diffs your lockfile against the base ref and collects changed resolved versions (including transitives).
692. Checks npm provenance via the attestations API for each `name@version`.
703. Falls back to version metadata for `dist.attestations`.
714. Emits file+line annotations in the lockfile.
725. If provenance exists for both the previous and new version, extracts GitHub `owner/repo` and branch from attestations and warns when they differ (repo changed or branch changed).
73
74## 🔒 Why this matters
75Trusted publishing links a package back to its source repo and build workflow, providing strong provenance guarantees. It helps ensure the package you install corresponds to audited source and CI.
76
77However, maintainers can still be phished or coerced into publishing without trusted publishing enabled, or switching to a non‑trusted path. In those cases, packages may still carry attestations, but the chain back to the trusted publisher can be weakened.
78
79This action:
80- Detects when a dependency update loses npm provenance (no attestations), loses trusted publisher (attestations but no trusted publisher marker), or loses [staged publishing](https://docs.npmjs.com/staged-publishing) (previous version was published via a staged release with a recorded approver; new version was not), and
81- Fails CI by default (configurable), before that change lands in your main branch.
82
83This is a stopgap until package managers enforce stronger policies natively. Until then, it offers a lightweight guardrail in CI.
84
85## ⚠️ Notes
86- Runs on Node 24+ and executes the TypeScript entrypoint directly.
87- `bun.lockb` is not supported. (You can generate a `bun.lock` with `bun install --save-text-lockfile`.)
88- Repository and branch change detection is best‑effort; attestation shapes vary and some packages omit repo/ref details.