How do you turn on npm provenance when a release tool publishes?

If a release tool publishes for you and you cannot add a flag to the command, turn on npm provenance in one of three places: set the NPM_CONFIG_PROVENANCE environment variable to true, add provenance true to publishConfig in package.json, or add provenance=true to an .npmrc file. You still need a supported cloud runner and an id-token permission.

The three documented methods

The npm provenance docs describe these options for third party publishing tools that do not directly invoke npm publish:

{
  "publishConfig": {
    "provenance": true
  }
}

The docs add that Yarn needs v4.9.0 or greater to publish with provenance.

What else must be true

Setting the option is not enough. From the same docs:

1. You publish from a supported cloud CI/CD provider on a cloud-hosted runner. The docs name GitHub Actions and GitLab CI/CD.
2. On GitHub Actions the job needs permission to mint an ID token, id-token: write.
3. Your package.json repository field must point at a public repository that matches, case-sensitively, where you publish from.
4. You need npm CLI 9.5.0 or later. The docs note that this often means updating npm beyond the version that ships with Node.js.
5. The first publish of a scoped public package also needs access set to public.

The Linux Foundation immutable record notice also applies to the public transparency log, so read it before you publish.

A GitHub Actions sketch

permissions:
  contents: read
  id-token: write
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          registry-url: 'https://registry.npmjs.org'
          package-manager-cache: false
      - run: npm ci
      - run: npx your-release-tool
        env:
          NPM_CONFIG_PROVENANCE: "true"

The docs' own example sets package-manager-cache to false with the comment never to use caching in release builds. That is worth copying: a poisoned cache feeding a release build is a known attack path.

Trusted publishing shortcut

If you set up trusted publishing instead, the docs say provenance attestations are generated automatically without the provenance flag, and long-lived tokens are no longer needed. See npm trusted publishing setup and common errors.

Verify it worked

1. Open the published version on npmjs.com and look for the green check next to the version.
2. Open the details and confirm the build summary, source commit and workflow file match your release.
3. On a consumer machine run the audit signatures command to check attestations.

If the badge is missing, check the permission, the runner type, the repository field and that your tool really reads the setting.

What provenance does not do

It does not prove the code is free of malicious content. Read what package provenance proves and what it does not.

Where Safeguard fits

Safeguard's SBOM generation and compliance and evidence automation help you keep a per-release record of what you shipped, alongside whatever attestations your registry provides. A free scan is at https://gold.safeguard.sh/scan.

Quick check

Sources

• npm docs: generating provenance statements
• npm docs: trusted publishing for npm packages

Last reviewed: 19 October 2026.