npm Trusted Publishing: Secure CI/CD with OIDC

Why use Trusted Publishing?

Traditional npm publishing from CI requires storing an npm automation token as a secret. This creates security risks:

GitHub Actions setup

name: Publish to npm

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write  # Required for OIDC
    environment: npm   # Optional: match your npm config
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'

      - run: npm ci
      - run: npm publish --provenance --access public

GitLab CI setup

publish:
  stage: deploy
  image: node:20
  id_tokens:
    SIGSTORE_ID_TOKEN:
      aud: https://registry.npmjs.org
  environment: production
  script:
    - npm ci
    - npm publish --provenance --access public
  rules:
    - if: $CI_COMMIT_TAG

Monorepo setup

Trusted Publishing works with monorepo tools. Each package needs its own trusted publisher configuration on npm.

With Lerna

Lerna 7+ has built-in OIDC support. Use the standard workflow:

- run: npx lerna publish from-git --yes

See Lerna's OIDC documentation for details.

With Changesets

Changesets uses npm's native publishing, so OIDC works automatically:

- run: npx changeset publish

With pnpm

- run: pnpm -r publish --access public

Troubleshooting

{
  "repository": {
    "type": "git",
    "url": "https://github.com/owner/repo.git"
  }
}

The npm UX problem

Setting up Trusted Publishing sounds straightforward, but npm's UX makes it tedious — especially for multiple packages.

The 2FA gauntlet (per package)

After the initial publish, enabling OIDC-only requires multiple steps — each requiring a separate 2FA code:

That's 6 two-factor authentication codes per package. For a monorepo with 10 packages, you're looking at 60 codes just to set up OIDC correctly.

Monitoring your publishes

With Trusted Publishing, every publish generates a provenance attestation. But you still receive npm's "Successfully published" emails — one per package, per version.

These emails show whether the publish was "via OIDC" (Trusted Publishing) or "via token". This is your signal for detecting misconfigured packages — if you see "via token" on a package that should be OIDC-only, someone missed the radio button step.

Frequently asked questions