How to Publish Monorepo Packages With npm Provenance and OIDC

npm provenance links each published package to the exact workflow run that built it; GitHub OIDC supplies the identity so no long-lived token is needed for the attestation.

Adding --provenance (or provenance: true in .npmrc) makes npm publish a signed statement about where and how the package was built. It requires the job to have id-token: write so the runner can obtain an OIDC token.

Steps

• Add permissions: id-token: write to the publish job.
• Run publish with --provenance (Changesets and pnpm forward it).
• Ensure the registry is the public npm registry, which supports provenance.
• Verify the provenance badge appears on the package page.

Workflow

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: https://registry.npmjs.org
      - run: pnpm install --frozen-lockfile
      - run: pnpm publish -r --access public --provenance
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Gotchas

• Provenance requires publishing from a supported CI (like GitHub Actions) with id-token: write; it fails from a laptop.
• You still need NODE_AUTH_TOKEN (or trusted publishing) to authorize the publish itself; OIDC here backs the attestation.

Related guides