npm token migration: Your CI/CD cutover guide

The clock is ticking on npm token migration. As of November 5, 2025, creating new classic tokens is disabled, and on November 19, 2025, all existing classic tokens will be revoked. Write-enabled granular tokens now default to a seven‑day lifetime (max ninety days), and 2FA enforcement is tightening with passkeys encouraged. If your pipelines still depend on a long‑lived NPM_TOKEN, plan your cutover now—not the night before your release.

npm token migration timeline: dates that matter

Here’s the thing: timelines are the difference between an orderly migration and a surprise outage during a Friday release.

Concrete dates and changes you can bank on:

• November 5, 2025: Classic token creation disabled in the website, CLI, and API. The npm token create command no longer makes classic tokens.
• November 19, 2025: Classic tokens are revoked. Pipelines still using them will fail to authenticate.
• Granular access tokens with write permissions: default expiration is seven days; maximum lifetime is ninety days. New write tokens enforce 2FA by default, with an optional CI bypass toggle.
• 2FA direction of travel: WebAuthn/passkeys preferred. New TOTP setups have been restricted; plan to move accounts toward passkeys.
• Trusted Publishing: available now via OIDC; requires npm CLI 11.5.1+ for a smooth experience.

Why the abruptness? A string of supply‑chain attacks (including a worm that spread via compromised maintainer accounts and stole secrets at scale) forced a defensive posture shift—short‑lived credentials, fewer broad‑scope tokens, and a push to OIDC‑based publishing.

Who’s impacted—and how hard?

If you publish packages (public or private), you’re in scope. But the blast radius depends on your setup:

High risk: GitHub Actions, Jenkins, or GitLab pipelines using a long‑lived classic NPM_TOKEN with publish rights. These will fail on November 19.

Moderate risk: Pipelines already on granular tokens but assuming long expirations. Seven‑day default means rotation overhead. You’ll need a rotation cadence or OIDC.

Lower risk: Workflows on Trusted Publishing (OIDC). No long‑lived write token to rotate; publishes exchange a short‑lived identity token during the job.

Hidden risk: tokens copied into self‑hosted runner images, Terraform/Ansible vars, internal automation (n8n, custom Node scripts), or old monorepo release jobs that nobody has touched this year. These are the ones that cause “why did prod fail?” messages at 2 a.m.

The decision: granular token or Trusted Publishing?

You’ve got two viable paths. Pick based on constraints, not nostalgia.

Path A: granular access tokens (fastest swap, more ops overhead)

Use this if you can’t move to OIDC yet (e.g., self‑hosted runners you can’t change this sprint, or a non‑supported CI). Create a new granular token scoped to exactly what you publish and where. Set the shortest expiration you can tolerate, and plan rotation.

Practical guardrails that help:

• Scope the token to a single package or scope; never “all packages” for convenience.
• IP‑restrict where feasible (cloud runners with stable egress).
• Use the Bypass 2FA option only for CI tokens and document who approved it.
• Automate rotation. A weekly job that creates a fresh token and updates your secret store beats “we’ll remember.”

Path B: Trusted Publishing (OIDC) (preferred, eliminates write tokens)

OIDC removes long‑lived write tokens from the loop. You authorize a repository and exact workflow filename on npm, grant id-token: write in your CI job, and the CLI requests a short‑lived token during npm publish. No secret to steal, nothing to rotate.

Gotchas to watch for:

• Workflow filename must match exactly what you configure on npm (including case and .yml extension).
• Cloud‑hosted runners only for now; most self‑hosted runners aren’t supported.
• OIDC is for publish only. If your build installs private dependencies, you still need a read‑only token for npm ci.
• Use npm CLI 11.5.1+ so provenance and OIDC flows behave as expected.

If you want a deeper dive on GitHub side limits and recent runner changes, we covered that in our GitHub Actions November 2025 changes breakdown.

Let’s get practical: a proven cutover plan

Below is the same playbook we’ve used on client migrations this fall. It’s conservative, reversible, and boring—on purpose.

Step 1: inventory and map risk

Search your org for where NPM_TOKEN appears. Check GitHub Actions secrets, environment secrets, Org secrets, self‑hosted runner env files, Jenkins credentials, and Dockerfiles or AMIs that might bake in the token. Document package names, repos, and which workflow publishes them.

Step 2: decide per package—granular token vs OIDC

For each package, choose Path A or B. If the repo already uses GitHub‑hosted runners, pick OIDC. If you’re on a custom runner you can’t change this cycle, pick a granular token with tight scope and a short lifetime. Note who owns rotation.

Step 3: stage the new auth side‑by‑side

Don’t yank the old token yet. Add the new mechanism and run a dry run publish (or publish to a canary tag). For OIDC, set permissions: id-token: write and actions/checkout early in the job. For granular tokens, create a token with the minimal permissions and set it as a repo secret.

Step 4: enable provenance and test the happy path

Publish one patch version with --provenance enabled from CI, then verify the package page shows provenance. Make sure your changelog/versioning automation still works and your dist-tag logic is untouched.

Step 5: cut traffic over and monitor

Swap the workflow to use OIDC or the new token, keep the classic token as a fallback secret that is not referenced. Ship a minor version during business hours, watch the job logs, npm page, and downstream install metrics. Only then delete the old token.

Step 6: clean up secrets everywhere

Remove the classic token at the user level and from every secret scope. Rebuild runner images to ensure no cached token survives. Rotate any read tokens used for private dependencies as a hygiene step.

Step 7: memorialize the policy

Add a SECURITY.md note stating that npm publishes must use OIDC, read tokens rotate every 30–60 days, and CI tokens may not be granted Bypass 2FA without approval. Boring policy beats exciting breaches.

CI/CD gotchas you’ll thank yourself for catching

Packaging systems are opinionated, and small mismatches can stall a release. A few edge cases we keep seeing:

• Workflow file name drift: You configured publish.yml on npm, but the repo uses release.yml. OIDC will fail silently until publish time.
• Monorepos: If each package publishes from a different workflow file, register each filename on npm or consolidate under one entry and call npm workspaces from that job.
• Private dependencies: OIDC won’t help your npm ci. Keep a read‑only granular token for installs, scoped to just the private packages.
• Self‑hosted runners: Trusted Publishing often requires cloud‑hosted runners. If you must use self‑hosted, stick to granular tokens while you plan a runner strategy.
• 2FA in local releases: Local maintainer publishes should expect enforced 2FA. Move maintainers to passkeys and make sure recovery keys are printed and stored securely.

If you want a fast checklist tailored to the Nov 19 deadline, we’ve published a companion piece: Fix CI before Nov 19.

Why this is happening: the security rationale

Zooming out, this isn’t a random policy change. The npm ecosystem saw large‑scale attacks this year that stole maintainers’ secrets and used compromised workflows to republish malware. Long‑lived, broad‑scope tokens were the accelerant. Shortening token lifetimes, revoking classics, and encouraging OIDC all shrink the useful window for an attacker and reduce the blast radius if a token leaks.

There’s a cultural shift embedded here too: registry publishes should prove who and what produced a build. That’s why provenance matters and why you’ll see passkeys prioritized over OTP codes. It’s not about checkbox security; it’s about traceability under pressure.

People also ask

Can I keep using classic tokens until November 19?

Yes—technically. But don’t. Treat November 12 as your internal freeze date. Cut over, watch a release in business hours, and remove the classic token before the registry does it for you.

Do I need 2FA for local publishes now?

Expect 2FA for writes, with WebAuthn/passkeys as the preferred method. Migrate maintainers to passkeys and store recovery codes in your password manager’s shared vault.

Does Trusted Publishing work with self‑hosted runners?

Not reliably yet. Plan to use cloud‑hosted runners for the publish step, or stay on granular tokens until support expands.

How do I handle monorepos with many packages?

Authorize the single workflow that performs multi‑package publishes, or register each workflow filename per package. Keep read tokens scoped to private packages only, and consider a dedicated publish job per package to simplify provenance.

Will this break private registries or proxies?

No, but you may need to issue a read‑only granular token for installs that go through a cache or proxy. Publishing to npm from behind a proxy still follows the same OIDC rules when applicable.

A 48‑hour cutover checklist

Give yourself two focused days and you’ll sleep better on November 18.

• Day 1 morning: inventory every place NPM_TOKEN appears. Flag any self‑hosted runner images.
• Day 1 afternoon: pick a path (granular vs OIDC) per package. Create tokens or configure Trusted Publishing. Add id-token: write permissions where needed.
• Day 1 late afternoon: dry run a publish or push to a canary tag. Verify provenance and registry metadata.
• Day 2 morning: cut over one high‑value package during business hours. Monitor logs and install metrics.
• Day 2 afternoon: remove classic tokens from secrets and user settings. Rebuild any base images. Document the new process.

What about security beyond npm?

Security debt rarely lives in one place. If this migration surfaced broader weaknesses—like stale runner images or missing SBOMs—tackle them now. For example, if your mobile stack leans on React Native, patch known issues and keep your release tooling locked down; we documented a recent CLI vulnerability that caught a few teams off guard.

What to do next

Practical next steps you can take today:

• Decide per package: granular token with rotation or OIDC Trusted Publishing.
• Set a hard internal freeze date before November 19 and ship a test release.
• Move maintainers to passkeys. Print recovery codes and store them properly.
• Enable provenance on publishes. Treat it as non‑optional.
• Write down the policy: who can create tokens, rotation cadence, and where secrets may not live.

If you want help, we’ve been guiding teams through this exact change. See what we deliver on our services page or reach out via contacts. For broader platform hygiene tied to this migration, our note on GitHub Actions November 2025 changes is a useful companion read.

Reference implementation sketch (so you don’t get stuck)

Here’s a minimal mental model for a GitHub Actions job that publishes with OIDC:

Permissions include id-token: write; the workflow filename matches exactly what you configured on npm; you run npm ci, build, then npm publish --provenance. For private installs during the build, a repo or environment secret holds a read‑only token scoped to specific private packages. No write token is stored anywhere.

Prefer a token path? Mirror that job but set a repo‑level NPM_PUBLISH_TOKEN secret that’s scoped to a single package, set to expire in seven days, and rotated on a weekly schedule. Lock down who can read or write that secret and alert on changes.

Want an end‑to‑end playbook that includes rollback checkpoints and a comms plan? We wrote one: NPM token migration: fix CI before Nov 19. For adjacent platform upgrades that can coincide with your release hardening, see our Node.js 25 upgrade playbook to avoid surprises when you bump runtimes during this cutover cycle.

Final thought

You don’t need to love these changes to benefit from them. Short‑lived tokens and OIDC reduce how much damage a leak can do, and provenance gives your customers confidence that the bits they install are the ones you intended to ship. Make the switch this week, verify it in daylight, and keep your package pipeline both secure and boring.