npm provenance needs a supported CI with a cloud-hosted runner, a public repository value in package.json that matches where you publish, the id-token write permission and npm CLI 9.5.0 or later. It also writes a signed record to a public log, so decide that you are comfortable with that.
The requirements
The npm documentation lists these conditions:
- Publish from GitHub Actions or GitLab CI/CD, on a cloud-hosted runner.
- Set a public repository value in package.json that matches the publish location, including letter case.
- In GitHub Actions, grant id-token write. GitLab uses an id_tokens entry with the sigstore audience.
- Use npm CLI 9.5.0 or later.
- Turn provenance on, through the publish flag, an environment variable, an npmrc line or the publishConfig field. Yarn needs 4.9.0 or later.
- For a first publish of a scoped package, add the public access option.
- If you use trusted publishing, provenance is generated automatically.
A minimal GitHub job looks like this.
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm publish --provenance --access public
For a longer walkthrough, see npm publish with provenance on GitHub Actions.
What becomes public
The attestation publicly links the package to its source and build instructions. The npm page says attestations are signed by Sigstore's public servers and logged publicly, and tells you to read the Linux Foundation Immutable Record notice before publishing. The page does not give a complete list of fields in the record, and does not describe limits for private repositories, so check it yourself if your source is private.
Plan for this in two ways. First, assume the repository name, workflow and commit are visible. Second, treat the log as public and long lived, and read the notice the docs point to.
What provenance does and does not tell a consumer
| Question | Answered by provenance? |
|---|---|
| Which repository and workflow built this tarball? | Yes |
| Was the source code reviewed or free of bugs? | No |
| Was the maintainer account safe? | Not directly |
| Is the package safe to install? | No |
We have written about the last row in does npm provenance stop slopsquatting and why valid provenance is not proof of safety. For a solo developer the value is auditability: if a bad release ever appears, the record shows where it came from.
Decision guide
- Public repo, GitHub Actions: turn it on. It is a small change.
- Private repo or self-hosted runner: read the page carefully; the docs list cloud-hosted runners as a requirement.
- Publishing from your laptop: provenance is not available on that path, which is one more reason to see publishing from CI or a laptop.
Quick check
Do I need the provenance flag if I use trusted publishing?
No. The npm docs say provenance is generated automatically with trusted publishing.
What should I check first if provenance does not match my repository?
The docs require the public repository value in package.json to match the publish location, including letter case. Check that first.
Sources
Last reviewed: 19 October 2026.
