npm Trusted Publishing: Ship Releases From CI Without an NPM_TOKEN Before January 2027

What is npm trusted publishing?

Trusted publishing lets a CI/CD workflow publish an npm package with OpenID Connect (OIDC) instead of a stored npm token. npm's docs describe it as "eliminating the need for long-lived npm tokens": each publish uses "short-lived, cryptographically-signed tokens that are specific to your workflow and cannot be extracted or reused."

It is not an npm invention. A paper from an Open Source Security Foundation (OpenSSF) working group describes Trusted Publishers as an authentication method any public package registry can adopt: CI exchanges an OIDC identity token for a short-lived, tightly scoped API token. PyPI shipped it first, in April 2023; RubyGems followed in December 2023, then crates.io and npm in July 2025 and NuGet in September 2025. npm's version became generally available on 31 July 2025.

Why move off NPM_TOKEN now?

Because the token path is closing, step by step. On 14 September 2025 GitHub was told about Shai-Hulud, a self-replicating worm that spread through compromised maintainer accounts and stole secrets, npm tokens among them. GitHub removed more than 500 compromised packages and announced that publishing would narrow to three options: local publishing with 2FA, granular tokens limited to seven days, and trusted publishing.

1. Jul 2025

   Trusted publishing generally available for GitHub Actions and GitLab.com runners.

2. Sep 2025

   Shai-Hulud. GitHub announces the move away from long-lived tokens.

3. Nov 2025

   Legacy (classic) access tokens removed. Only granular tokens remain.

4. Aug 2026

   Bypass-2FA tokens can no longer change email, password, 2FA, tokens or maintainers.

5. Sep 2026

   Stage-only tokens: CI can submit a version, a maintainer approves it with 2FA.

6. Oct 2026

   npm stage publish can create a brand-new package.

7. Jan 2027

   Target date to remove direct publishing with access tokens.

January 2027 is a target, not a promise, and the two sources word its scope differently. The changelog says npm "is targeting" the removal of direct publishing through bypass-2FA tokens. The access token docs say "The ability to publish new package versions directly with a granular access token will be removed in January 2027". Either way, a release job that runs npm publish with a token is on borrowed time.

Token, trusted publisher or stage-only token: which should publish?

Three ways a CI job can still get a version onto the registry, compared on what matters when a secret leaks.

The pick is short: use a trusted publisher wherever your CI supports one, and a stage-only token everywhere else.

How does trusted publishing check a workflow?

Nothing secret is stored. Each run asks its CI provider for a fresh identity and trades it for a publish credential that dies with the run.

How do you set up trusted publishing on GitHub Actions?

1. Check the versions

   The job needs npm CLI 11.5.1 or later and Node 22.14.0 or later. Print npm --version in the job; if it is older, update npm before the publish step.

2. Match repository.url

   The repository.url in package.json must match your GitHub repository exactly. Forks that never changed it fail here.

3. Register the publisher

   On npmjs.com open the package, then Settings, then Trusted publishing, and pick GitHub Actions. Fill in the owner, the repository, the workflow file name only (publish.yml, not the path) and the environment if you use one. Choose the allowed actions: npm stage publish is always allowed, npm publish is your choice.

4. Edit the workflow

   Grant id-token: write, run on a GitHub-hosted runner, and remove NODE_AUTH_TOKEN from the publish step.

5. Publish within 2 days

   A new trusted publisher must complete its first successful publish within 2 days, or it expires and has to be deleted and created again.

6. Lock the door behind you

   In the package's Settings, Publishing access, choose "Require two-factor authentication and disallow tokens", then revoke the automation tokens you no longer need.

What does the release workflow look like?

A tag-triggered release, adapted from the example in npm's docs. The only lines that make it trusted are the id-token permission and the absence of any token on the publish step.

name: Publish
on:
  push:
    tags: ['v*']

permissions:
  id-token: write   # lets the job request an OIDC token
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest   # GitHub-hosted, not self-hosted
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          registry-url: 'https://registry.npmjs.org'
          package-manager-cache: false
      - run: npm ci
      - run: npm test
      - run: npm publish   # no NODE_AUTH_TOKEN here

Prefer the command line? With npm 11.15.0 or later, 2FA on your account, write access to a package that already exists, and an interactive login (not a bypass-2FA token), one command does step 3:

npm trust github my-package --file publish.yml --repo my-org/my-package --allow-publish

Why does the publish fail with ENEEDAUTH?

"Unable to authenticate" (ENEEDAUTH) usually means the job's identity or setup does not match what npm expects. Check these in order.

Workflow file name differs

Fields are case-sensitive and the name needs its .yml or .yaml extension.

Self-hosted runner

Not supported. Use a GitHub-hosted runner, GitLab.com shared runners or CircleCI cloud.

No id-token: write

Without it the job cannot request an OIDC token at all.

Reusable or manual workflow

With workflow_call or workflow_dispatch, npm checks the calling workflow's name, and both workflows need id-token: write.

repository.url mismatch

It must match the GitHub repository exactly.

npm ci fails, not the publish

Trusted publishing covers the publish only. Private dependencies still need a read-only granular token for the install step.

Which path fits your CI?

Before you delete the old token

• The trusted publisher has completed one real publish (within its 2-day window).
• If a person should approve each release, the trusted publisher allows npm stage publish only.
• Every package you publish has its own trusted publisher: the setting is per package.
• Install steps that need private packages use a read-only token, never the old write token.
• Publishing access is set to "Require two-factor authentication and disallow tokens".
• Old automation tokens are revoked on npmjs.com and removed from CI secrets.

Questions maintainers ask