NPM Trusted Publishing

Overview

Set up secure npm publishing from GitHub Actions using OIDC trusted publishing instead of long-lived NPM_TOKEN secrets.

When to Use

• Setting up npm publish workflow in GitHub Actions

• Migrating from NPM_TOKEN to trusted publishing

• Adding provenance attestations to packages

• Publishing monorepo packages

Quick Reference

Requirement Implementation

GitHub Actions permission id-token: write

package.json field repository.url matching GitHub repo

npm publish flag --provenance

npmjs.com setup Configure trusted publisher per package

Implementation

1. GitHub Actions Workflow

permissions: contents: write id-token: write # Required for OIDC

jobs: publish: runs-on: ubuntu-latest 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 run build

  # No NODE_AUTH_TOKEN needed - uses OIDC
  - run: npm publish --access public --provenance

2. package.json Repository Field

{ "name": "@scope/package", "repository": { "type": "git", "url": "git+https://github.com/owner/repo.git", "directory": "packages/subpackage" } }

Monorepo note: Include directory field for packages not at repo root.

3. npmjs.com Configuration

For each package, go to Settings > Publishing access and add:

• Repository: owner/repo

• Workflow: publish.yml (or your workflow filename)

• Environment: (optional)

Common Mistakes

Mistake Fix

Missing --provenance flag Add to npm publish command

Wrong URL format Use git+https://github.com/...

Missing id-token: write

Add to workflow permissions

Forgot npmjs.com setup Configure trusted publisher in package settings

Using NODE_AUTH_TOKEN Remove - OIDC handles auth

Outdated npm version Add npm install -g npm@latest step (see below)

npm Version Requirement

GitHub Actions runners may have an outdated npm version that doesn't properly support OIDC trusted publishing. This causes a confusing error:

npm notice Access token expired or revoked. Please try logging in again. npm error code E404 npm error 404 Not Found - PUT https://registry.npmjs.org/@scope%2fpackage - Not found

Solution: Update npm to latest before publishing:

• uses: actions/setup-node@v4 with: node-version: "20" registry-url: "https://registry.npmjs.org"

• name: Update npm to latest run: npm install -g npm@latest

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

See GitHub Community Discussion #173102 for details.

Reference

• npm docs: https://docs.npmjs.com/trusted-publishers