Here’s the situation: the npm token migration is real, dated, and imminent. As of November 5, 2025, creating classic npm tokens was shut off across the website, CLI, and API. On November 19, 2025, all remaining classic tokens are revoked. If your CI/CD publishes with a classic token, you’ll hit 401/403 errors and your release will stall. The good news: you can cut over in days—not weeks—if you follow a disciplined plan.
What exactly changes—and when
Two key dates matter. First, on November 5, 2025, npm stopped issuing classic tokens via the site and the npm token create command. New write‑enabled granular tokens now enforce 2FA by default, a “Bypass 2FA” toggle exists for CI, and write granular tokens cap out at a 90‑day lifetime (existing ones set past February 3, 2026 were adjusted back to that date). Second, on November 19, 2025, classic tokens are permanently revoked. Local long‑lived publishing flows are replaced with short session tokens; you’re expected to move to scoped, short‑lived credentials or to Trusted Publishing via OIDC.
Trusted Publishing lets npm verify your CI identity without a secret in your repo or org. On GitHub Actions and GitLab.com shared runners, your workflow requests a short‑lived OIDC token during npm publish; npm exchanges it for a registry token that can’t be reused. For GitHub Actions specifically, that means granting id‑token: write in your workflow and registering the workflow file on npm for that package. One important limitation: as of today, Trusted Publishing supports cloud‑hosted runners, not self‑hosted. Plan accordingly.
Who’s affected—and what breaks on Nov 19
If any of these describe your pipeline, you’re on the cliff edge:
• Your release job uses NPM_TOKEN or an env var injected from secrets to run npm publish to the public registry. If that secret is a classic token, it dies November 19.
• You rely on a long‑lived token for internal tools like npm dist‑tag updates or housekeeping scripts executed from CI.
• You do local publishing from a developer machine with a classic token cached in ~/.npmrc and skip 2FA prompts. Expect to re‑authenticate with short sessions or switch to OIDC‑backed automated publishing.
Other flows keep working with adjustments. Installing private packages in CI still needs a token, but it can be a read‑only granular token scoped to the org or package. Publishing should move to OIDC where possible. If you absolutely must use a token for publishing (for example, a non‑supported CI), you’ll create a short‑lived granular token with the right scopes and, for noninteractive jobs, enable the CI 2FA bypass on that token.
npm token migration: a last‑week cutover plan
If you have four business days, you can land this with zero downtime. Use this sequence and don’t skip the validation steps.
1) Inventory: find every publish and write path (90 minutes)
Search your org for any npm publish, npm access, npm team, or npm dist‑tag commands in pipelines, reusable workflows, and scripts. Grep for NPM_TOKEN and _authToken. Don’t forget scheduled jobs and release bots. Capture: repo, workflow file, job name, command, and the secret’s name.
2) Decide per package: OIDC or token (30 minutes)
Use this quick rubric:
• Public packages on GitHub/GitLab cloud runners → choose Trusted Publishing.
• Private packages on supported cloud runners → Trusted Publishing works for publishing; you still need a read token for npm ci if you install private deps.
• Self‑hosted runners or other CI → use granular tokens for now (read‑only for installs; write for the single publish step), then plan to migrate to OIDC when supported.
3) Prepare Trusted Publishing (60 minutes)
Per npm package: open Settings → Trusted Publisher, select your provider, and register the exact workflow filename (case‑sensitive). In your workflow, add permissions: id‑token: write and run on a trusted trigger like tag push (for example, v* tags). Keep contents: read. Use npm@latest (or at least npm 11.5.1+) to ensure OIDC detection. Publish from a clean job: checkout, setup‑node, build, test, then npm publish—no secret required.
4) Rotate install tokens (45 minutes)
For pipelines installing private packages, replace any classic tokens with read‑only granular tokens. Scope them to the minimal orgs/packages. Keep expirations short (e.g., 30–60 days) and add them via your CI’s secret store. Confirm you didn’t accidentally grant write. If your CI installs from multiple registries, separate tokens per registry to avoid cross‑leak risk.
5) Flip CI 2FA bypass only if you must (15 minutes)
When you create a write granular token for publishing in a non‑OIDC CI, “Bypass 2FA” is off by default. Enable it only for that token and document who owns rotation. Your long‑term direction should be OIDC to eliminate persistent write tokens entirely.
6) Dry run on a canary package (60 minutes)
Pick one package and walk the new path end‑to‑end. If you’re using Trusted Publishing, create a v0.0.0‑canary tag, push, and verify the workflow: OIDC token is issued, provenance is attached (if applicable), and no secrets are read. If you’re using granular tokens, verify the token scope and expiration in the npm settings and that the publish succeeds with the bypass setting as intended.
7) Switch production packages (half‑day)
Roll through your inventory. For each package: wire up Trusted Publishing or swap the token secret, commit the workflow changes, and tag a release. Watch for two common mistakes: mismatched workflow filenames (they must match what you registered on npm) and missing id‑token: write permission. Document each package’s new auth mode in a simple table for your team.
People also ask
Do I need 2FA for CI tokens?
By default, new write granular tokens enforce 2FA, which is great for interactive use but blocks headless jobs. The CI‑bypass option exists for precisely that case. Use it sparingly and track those tokens separately. Better: move to OIDC so there’s no persistent token involved at all.
Does Trusted Publishing support self‑hosted runners?
Not yet. Today it’s supported on GitHub Actions (GitHub‑hosted) and GitLab.com shared runners. If you’re on self‑hosted, use granular tokens as a stopgap and keep expirations short until self‑hosted support lands.
What npm version do I need?
Use npm 11.5.1 or newer so the CLI can detect OIDC environments and attach provenance when publishing. Older CLIs may still publish, but you’ll miss security improvements and you might hit rough edges when the registry expects OIDC‑aware behavior.
Will this impact our GitHub Actions policies next month?
Likely. On December 8, 2025, GitHub is changing how pull_request_target and environment branch protections evaluate refs. If your PR workflows deploy or touch secrets, plan those adjustments now while you’re already in the pipeline. We put together a pragmatic playbook for the December 8 change so you don’t get surprised by ref mismatches.
The non‑obvious pitfalls (learned the hard way)
• Wrong file name breaks OIDC. npm validates the workflow by the exact filename you register. A common miss is renaming publish.yml to release.yml without updating npm settings. Result: “Unable to authenticate.”
• Private installs still need a token. Trusted Publishing only covers npm publish. If your build pulls private packages, keep a separate read‑only token for installs.
• Token reuse between orgs. Teams often reuse one token for multiple registries or scopes. Don’t. Issue separate tokens with minimal scopes per registry to contain blast radius.
• In‑repo scripts that shell out to npm. If you tuck npm publish inside a bash helper, your security reviewers won’t see it. Grep your repo and centralize the publish step in one visible workflow job.
• Expiring tokens mid‑sprint. With a 90‑day max lifetime for write tokens, calendar reminders matter. Automate rotation alerts or centralize token expiry tracking so you don’t learn about it during a release.
Minimal reference workflow: GitHub Actions + OIDC
Trigger on tag push (for example, v*). Grant permissions: id‑token: write and contents: read. Steps: checkout, setup‑node, install, test, build, publish. No secret input for npm publish. Keep the job fast and auditable. If you need a separate job to generate artifacts, pass them via the workspace; don’t persist a token anywhere.
A quick security model upgrade
This migration forcibly nudges teams from “shared, long‑lived write tokens” to “short‑lived, narrowly scoped credentials”—or no persistent tokens at all. Practically, it reduces the chance a leaked environment variable or a verbose build log exposes publishing power. It also gives you provenance on public packages when publishing from supported CI, which makes incident response and consumer trust better.
What to do next (today and this week)
• Today (Nov 15): run the inventory, choose OIDC or tokens per package, and set npm to use Trusted Publishing for at least one canary package.
• Tomorrow: rotate read‑only install tokens for private deps, and wire id‑token: write in your publishing workflow. Validate on a canary tag.
• Mid‑week: migrate the rest of your packages, document owners and rotation dates, and switch your release process to tag‑driven publishing.
• Before Nov 19: delete any lingering classic tokens and lock down who can create new write tokens. Put calendar reminders for granular token expirations.
Helpful resources and next steps with us
If you want a deeper dive on timelines and testing tactics, read our practical guide to beat the Nov 19 cutoff. If your team also relies on pull_request_target in GitHub Actions, don’t miss our December 8 playbook to avoid surprises when ref evaluation changes. If you’d like hands‑on help hardening your CI/CD and shipping without drama, here’s what we do for engineering teams and how to reach us.
FAQ edge cases
We publish multiple packages from a monorepo—how many trusted publishers do we need?
Trusted Publishing is configured per package on npm. You can point multiple packages at the same workflow file, or different files, as long as each package’s configuration matches exactly. In practice, most teams centralize on one “release.yml” per repo and use job inputs to select which packages to publish on a given tag.
Can we mix OIDC for public packages and tokens for private ones?
Yes. Use OIDC for public publishing, and keep a read‑only granular token for installing private packages. If you publish private packages, you can stay on tokens temporarily, but keep lifetimes short and rotation automated.
Do we have to enable provenance?
No, but you should. With npm versions that support it, provenance adds verifiable build metadata to your public release. Consumers increasingly expect it, and some enterprise allow‑lists will start requiring it.
Zooming out
Migrations like this feel inconvenient until you remember why they exist. Attackers love static secrets with broad scope and long lifetimes. Moving the ecosystem to short‑lived, tightly scoped credentials—and increasingly to OIDC—shrinks their playground. You’ll do a few hours of plumbing now, and you’ll sleep better every release after.
