npm Trusted Publishing, OIDC, and what changed

The foundation

First: what is Trusted Publishing?

A conventional GitHub Actions workflow often stores an npm token as a repository secret:

env:
  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

That token is a long-lived credential. If it is exposed, an attacker may be able to publish a malicious version until the token is detected and revoked.

Trusted Publishing replaces that permanent write credential with a short-lived, cryptographically signed OIDC identity issued to the running workflow.

GitHub Actions
      │
      │ temporary OIDC identity
      ▼
     npm
      │
      │ trusts this repository and workflow
      ▼
publish or stage allowed

The workflow requests permission to obtain an identity token:

permissions:
  id-token: write
  contents: read

steps:
  - run: npm publish

The npm CLI detects the OIDC environment and exchanges that identity for short-lived publishing authorization. No NPM_TOKEN is required for the publish operation.

The September 3 change

One package can now trust several release paths

Imagine @stackmoments/ui has separate workflows for stable and prerelease versions:

.github/workflows/publish.yml
        └── @stackmoments/ui 1.5.0

.github/workflows/prerelease.yml
        └── @stackmoments/ui 1.6.0-beta.1

Previously, one trusted-publisher configuration per package made this awkward. Additional release paths could require workflow workarounds or a long-lived npm token.

Now the same package can define multiple independently authorized configurations:

Trusted Publisher 1
Repository: stackmoments/ui
Workflow: publish.yml
Environment: production

Trusted Publisher 2
Repository: stackmoments/ui
Workflow: prerelease.yml
Environment: beta

Trusted Publisher 3
Repository: stackmoments/release-tools
Workflow: release.yml
Environment: production

npm authorizes the operation when the incoming OIDC identity matches any one configuration. The configurations behave like an allow-list:

               ┌── publish.yml ─────── ✓
npm package ────┼── prerelease.yml ──── ✓
               └── release.yml ─────── ✓

Where multiple configurations help

Each path can use its own repository, workflow filename and optional environment. npm currently allows up to ten trusted publishers per package.

Beyond the headline

The announcement contains three meaningful updates

Staging changes the failure path of a compromised workflow:

GitHub Actions
      │ OIDC
      ▼
npm stage publish
      ▼
malware scan
      ▼
maintainer approval
      ▼
public npm registry

With direct publishing, compromised release automation can push straight to the registry. With stage-only authorization, the workflow can prepare a version, but it cannot make that version public without the later scan and approval gate.

Architecture recommendation

Prefer identity, staging and review over permanent write secrets

For packages that can use supported cloud-hosted CI, the stronger release design is:

1. Authorize the exact repository, workflow and environment in npm.
2. Grant the workflow only id-token: write and the other permissions it actually needs.
3. Use npm stage publish for automated releases where practical.
4. Wait for malware scanning, then require an authenticated maintainer to approve.
5. Restrict or revoke traditional write tokens after the OIDC path is proven.

Eligible public packages published from public GitHub or GitLab repositories through Trusted Publishing also receive npm provenance attestations automatically. Those attestations help consumers verify where and how a package was built.

One boundary to remember

Publishing authentication is not installation authentication

Trusted Publishing authenticates npm publish and npm stage publish. It does not automatically give npm ci access to private dependencies.

# Private dependency installation
- run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_READ_TOKEN }}

# Package publication
- run: npm publish
  # OIDC — no publishing token

If a release build installs private packages, npm recommends a granular read-only token for that step and OIDC for publication. This is still substantially safer than placing a permanent write token in CI.

In one sentence

What should you remember?

One npm package can now trust several specific CI release workflows through OIDC, while stage-only permissions, malware scanning and human approval make the path to the public registry safer.