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