npm-oidc-publish

Publish to npm with OIDC trusted publishing

npm "trusted publishing" lets a GitHub Actions workflow npm publish without a long-lived NPM_TOKEN — it authenticates via OIDC and stamps provenance automatically. Works for any package; nothing language- or framework-specific.

The workflow

.github/workflows/publish.yml:

name: publish
on: { release: { types: [published] } }
permissions:
  contents: read
  id-token: write      # <- this is what enables OIDC
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 24 }   # npm >= 11.5 supports OIDC; node 24 is safe
      - run: npm ci                    # needs a committed package-lock.json
      - run: npm test
      - run: npm publish               # no token, no --otp; provenance is automatic

• Scoped public package? add "publishConfig": { "access": "public" } to package.json (and a "files" array so the build actually ships).
• A TypeScript build runs via "prepare": "npm run build" on npm publish.

The chicken-and-egg (every new package hits this)

You cannot configure a trusted publisher for a package that doesn't exist on npm yet, and the OIDC publish needs that config to exist. So the first publish is manual:

1. npm publish locally → enter your 2FA OTP (npm publish --otp=<code>). This creates 0.1.0.
2. On npmjs.com → the package → Settings → Trusted Publisher → GitHub Actions: set the repo (owner/repo), the workflow filename (publish.yml), and leave the environment blank (unless you actually use one).
3. From then on it's hands-free: gh release create vX.Y.Z --notes "..." triggers the workflow and publishes via OIDC.

If the workflow's npm publish fails with ENEEDAUTH ("requires you to be logged in"), the trusted publisher isn't configured yet, or the workflow filename / repo doesn't match what you registered on npm — it's a config problem, not code. (npm ci + npm test passing then npm publish failing is the tell.)