Npm Trusted Publishing Oidc Setup

---
name: npm-trusted-publishing-oidc-setup
description: >-
  Set up npm package publishing via GitHub Actions using Trusted Publishing (OIDC) instead of a long-lived NPM_TOKEN secret. Use when: the user asks to publish an npm package via CI/CD, set up a publish workflow, or automate npm releases; npmjs.com shows the 'security risks with this option... use Trusted Publishing instead' warning; or you are about to recommend an npm automation token + GitHub secret. Key gotchas: Node 24 required (npm 11.5.1+); the publish step must have NO NODE_AUTH_TOKEN env var at all; workflow needs permissions: id-token: write; package.json repository.url must match the GitHub repo; the FIRST publish of a new package cannot use OIDC; the Trusted Publisher must be configured manually on npmjs.com. The full ten-point gotcha list and release flow live in the body.
created_at: "2026-08-09"
---

# Npm Trusted Publishing Oidc Setup

Set up npm package publishing via GitHub Actions using Trusted Publishing (OIDC) instead of a long-lived NPM_TOKEN secret. Use when: the user asks to publish an npm package via CI/CD, set up npm publish workflow, create a publish.yml, automate npm releases, or you are about to recommend creating an npm automation token + GitHub secret; npmjs.com shows the security warning 'There are security risks with this option. For automation or CI/CD uses, please use Trusted Publishing instead'; or you need the OIDC requirements/gotchas for npm publishing. Covers the DENSE gotcha set: (1) Node 24 required (ships npm 11.5.1+ which is the minimum for OIDC); Node 22 only ships npm 10 and will fail. (2) NO NODE_AUTH_TOKEN env var on the publish step — it must be COMPLETELY ABSENT (not empty string) so npm falls back to OIDC token exchange. (3) Workflow needs permissions: id-token: write at job or workflow level. (4) repository.url in package.json MUST match the GitHub repo (provenance validation checks this); npm expects git+https://github.com/<org>/<repo>.git prefix. (5) package-manager-cache: false recommended for release builds. (6) --provenance flag on npm publish (keep it even if some docs say automatic). (7) The FIRST publish of a new package CANNOT use OIDC — the package must already exist on npm; publish the first version manually or with a token, then switch to OIDC. (8) User must manually configure the Trusted Publisher on npmjs.com: package settings -> Trusted Publisher -> GitHub Actions -> fill org/repo/workflow-filename/environment/allowed-actions. (9) The id-token: write permission lets GitHub Actions mint short-lived OIDC tokens scoped to that single run; npm exchanges these for a publish token — no stored credentials, no OTP. (10) Release flow after setup: npm version patch && git push --follow-tags (CI detects v* tag, publishes automatically). Distinct from github-actions-token-pr-creation-permission (repo-level PR-creation switch, a different GitHub Actions permission layer).

## Instructions

TODO: Add specific instructions based on observed patterns.