NPM Trusted Publishing

Default output: return only the result, blockers, and required evidence. Omit preambles, process narration, repeated context, confidence scores, and follow-up offers. Use at most five bullets unless a required artifact or schema needs more.

npm Trusted Publishing

Publish npm packages from GitHub Actions without long-lived tokens. Uses OIDC for authentication and generates provenance attestations automatically.

How It Works

1. GitHub Actions workflow runs on tag push
2. Workflow requests short-lived OIDC token from GitHub
3. npm exchanges OIDC token for publish token via registry
4. Package publishes with provenance attestation (supply-chain security)
5. No NPM_TOKEN secret needed — ever

Prerequisites

npmjs.org (one-time per package)

1. Go to https://www.npmjs.com/settings/
2. Packages → your package → Settings → Trusted publishing
3. Provider: GitHub Actions
4. Organization or user: matches GitHub username exactly (case-sensitive)
5. Repository: matches repo name exactly (case-sensitive)
6. Workflow filename: publish.yml (exact — not publish.yaml)
7. No environment name unless using GitHub deployment environments

package.json

{
  "name": "@scope/package-name",
  "version": "1.0.0",
  "repository": {
    "type": "git",
    "url": "https://github.com/user/repo"
  },
  "publishConfig": {
    "access": "public"
  }
}

Requirements:

• repository.url matches https://github.com/<user>/<repo> (no .git suffix)
• Package must be public (private packages cannot use provenance)
• Repository must be public (private repos cannot generate provenance)

Complete Working Workflow

name: Publish to npm

on:
  push:
    tags:
      - 'v*'
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to publish'
        required: true
        type: string
      dry_run:
        description: 'Dry run'
        required: false
        type: boolean
        default: false

permissions:
  contents: read
  id-token: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '24'
          registry-url: 'https://registry.npmjs.org'

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm run build

      - name: Publish to npm
        if: <!-- not a dry run -->
        run: npm publish --access public --provenance

Node Version Note

For Node 20/22: Use npx npm@11 publish instead of npm publish.

Multi-Package Workspaces

For monorepos with multiple publishable packages:

- name: Publish core
  working-directory: ./packages/core
  run: npm publish --access public --provenance

- name: Publish toolkit
  working-directory: ./packages/toolkit
  run: npm publish --access public --provenance

Dry Run

Test without publishing:

- name: Dry run
  run: npm publish --dry-run --access public --provenance

Provenance Verification

After publish:

# Confirm version is live
npm view @scope/package version

# Confirm provenance attestation exists
npm view @scope/package dist.attestations.provenance

# View full provenance details
npm view @scope/package --json | jq '.dist.attestations'

On npmjs.com package page, look for the "Provenance" badge.

Debugging Failed Publishes

Check npm version

npm --version  # Must be 11.x for trusted publishing

Check OIDC env vars

- run: |
    echo "ACTIONS_ID_TOKEN_REQUEST_URL: ${ACTIONS_ID_TOKEN_REQUEST_URL:+set}"
    echo "ACTIONS_ID_TOKEN_REQUEST_TOKEN: ${ACTIONS_ID_TOKEN_REQUEST_TOKEN:+set}"

Check trusted publisher config

• Org/user, repo, and workflow filename are all case-sensitive
• npm does NOT validate the config on save
• Must match exactly: https://github.com/Org/Repo vs https://github.com/org/repo

Common errors

Security Best Practices

• ✅ Use permissions: id-token: write (minimal)
• ✅ No NPM_TOKEN secret needed
• ✅ No --provenance flag needed (automatic on GitHub Actions)
• ❌ Never commit .npmrc with auth tokens
• ❌ Never use secrets.NPM_TOKEN in workflow
• ❌ Never use long-lived publish tokens

Related

• ci-cd-and-automation — General CI/CD patterns
• shipping-and-launch — Pre-launch checklists
• security-and-hardening — Secrets management