Publishing provenance from GitHub Actions
npm packages built on GitHub Actions can now be published with verifiable provenance by adding the --provenance flag to the publish command. This metadata lets consumers confirm that a package was built from a specific source repository commit using a known set of build instructions.
The provenance statement records details about the source repository, the commit that triggered the build, and the build configuration used to produce the package.
_type: https://in-toto.io/Statement/v0.1
subject:
- name: pkg:npm/[email protected]
digest:
sha512: 16bf7e5b59e40522190a425047b8c39ffcc8d145cdb15a69fbb9834240a764e2311bda7ac8d5c1c7dc67b47b1f532607139e570e4915577fab61bae4cc079eb0
predicateType: https://slsa.dev/provenance/v0.2
predicate:
buildType: https://github.com/npm/cli/gha/v2
builder:
id: https://github.com/actions/runner
invocation:
configSource:
uri: git+https://github.com/sigstore/sigstore-js@refs/heads/main
digest:
sha1: 5b8c0801d1f5d105351a403f58c38269de93f680
entryPoint: ".github/workflows/release.yml"
environment:
GITHUB_EVENT_NAME: push
GITHUB_REF: refs/heads/main
GITHUB_REPOSITORY: sigstore/sigstore-js
GITHUB_REPOSITORY_ID: '495574555'
GITHUB_REPOSITORY_OWNER_ID: '71096353'
GITHUB_RUN_ATTEMPT: '1'
GITHUB_RUN_ID: '4503589496'
GITHUB_SHA: 5b8c0801d1f5d105351a403f58c38269de93f680
GITHUB_WORKFLOW_REF: sigstore/sigstore-js/.github/workflows/release.yml@refs/heads/main
GITHUB_WORKFLOW_SHA: 5b8c0801d1f5d105351a403f58c38269de93f680
materials:
- uri: git+https://github.com/sigstore/sigstore-js@refs/heads/main
digest:
sha1: 5b8c0801d1f5d105351a403f58c38269de93f680
Documentation for the public beta is available on npmjs.com, and an example provenance statement can be viewed here.
Why provenance matters for supply chain security
Recent supply chain attacks against popular npm packages such as UAParser.js, Command-Option-Argument, and rc have shown a pattern: attackers rarely compromise source code directly. Instead, they steal publish credentials and release malicious versions under a legitimate maintainer's identity.
Open source code itself enjoys a degree of inherent trust because anyone can audit it. That trust does not extend to the published artifact. The build process that turns source code into a distributable package is a black box, leaving consumers with no way to verify that the package they install was actually derived from the source they reviewed.
The missing piece is visibility into how source code becomes a published package. Provenance provides exactly that: a verifiable record linking an artifact to its originating commit and the build steps that produced it.
Applying the SLSA model to npm
npm's provenance statements follow the SLSA (Supply-chain Levels for Software Artifacts) specification. The schema defines a subject (the published package), input materials (source repository and commit SHA), and a buildConfig describing the build and publish steps. Together these three elements establish a clear chain from source code to registry artifact.
Building provenance on a trusted CI/CD platform is essential. When a package is built on GitHub Actions, the platform knows the exact commit that triggered the build and the workflow instructions executed. This visibility makes tampering much harder to hide.
Signing with OIDC and Sigstore
Instead of relying on maintainer-managed signing keys, npm anchors trust in the CI/CD environment itself. The build job's identity, expressed as an OpenID Connect token, is used to obtain a short-lived X.509 signing certificate from Sigstore's Fulcio certificate authority.
The signing process works as follows:
A single-use keypair is created and used to sign the provenance statement, then immediately discarded. No long-lived keys need to be managed. Anyone inspecting the signing certificate can verify the signature and see the identity of the CI job that created it.
Sigstore's public certificate authority accepts OIDC tokens from conforming CI/CD providers. Today that means GitHub Actions; support for other platforms is in progress.
Verification for consumers
Provenance only helps if consumers can actually check it. During signing, the attestation is uploaded to Sigstore's Rekor transparency log. This public, tamper-evident log makes it possible to detect retroactive modification of provenance data or published package contents.
When a package with provenance is published, the registry validates the signature and signing certificate identity before accepting the version, which prevents spoofing. Packages with verified provenance display a badge next to their version number on npmjs.com:
The npm CLI (available in npm 9.5.0+) can also verify provenance attestations for installed dependencies:
npm audit signatures
Roadmap and ecosystem efforts
Future work includes adopting version 1.0 of the SLSA provenance specification, adding support from other cloud CI/CD providers, verifying that the recorded source repository and commit actually exist, and building tools to manage access between CI/CD environments and the npm registry.
GitHub is working on these capabilities through the OpenSSF, where it participates in the working group for securing software repositories. The goal is to extend similar provenance mechanisms across other platforms and package ecosystems.
