npm Token Migration: The Nov 19 Cutover Playbook

Here’s the situation: npm classic tokens are being sunset, and on November 19 they’re permanently revoked. If your org hasn’t started npm token migration to granular tokens—or better, to trusted publishing—you’re gambling with release outages. The good news: a disciplined two‑phase cutover (inventory → rotate → harden) keeps your pipelines moving and actually improves security posture the same week.

What changed on November 5—and what breaks on November 19

Let’s anchor the facts with dates and behaviors so you can plan precisely:

• As of November 5: you can’t create classic tokens anymore. New write‑capable granular tokens enforce 2FA by default, and granular write tokens now have a hard 90‑day max lifetime. If any tokens were set to expire after February 3, 2026, they’ve been shortened to that date.
• On November 19: all classic tokens are revoked. Also, the old long‑lived local publishing tokens are replaced with short 2‑hour session tokens for manual publishes.

Translation for busy teams: any CI that still relies on classic tokens will fail on Nov 19. Maintainers who publish from laptops will see new 2FA and session‑token behavior, which is safer but different. If you use granular tokens with write permissions in CI, you may need the “bypass 2FA” flag for noninteractive publishing—or, better, switch those jobs to trusted publishing with OIDC and skip tokens entirely.

The stakes for your CI/CD, spelled out

I’ve walked several orgs through dry runs this week. Here’s what actually goes wrong if you do nothing:

• Silent 401s during publish: Pipelines attempt npm publish with a classic token and get unauthorized. Build passes until the release step, then bombs.
• Manual hotfixes by maintainers: A maintainer tries to publish locally and hits 2FA or session token behavior—then cuts corners to “get it out” and accidentally widens token scope. Don’t be that team.
• Read vs write confusion: A pipeline only needs to npm ci private packages but accidentally uses a write‑scoped token. Unnecessary risk, and now you’ve got rotation churn every 90 days.
• Self‑hosted runners: People assume trusted publishing will work on their bespoke runners. It doesn’t if the provider isn’t supported; plan for tokens (read‑only or write with bypass), or move that job to a supported hosted runner.

Your 7‑step npm token migration checklist

Do this in order. It’s the fastest safe path I’ve found.

1. Inventory tokens and surfaces
   Search your org for NPM_TOKEN, NODE_AUTH_TOKEN, and _authToken in .npmrc, CI secrets, and container build args. Map each use to a repo, environment, and job name.
2. Classify each use case
   Tag jobs as one of: a) publish, b) install private packages only, c) both. Note where they run (GitHub Actions hosted runners, GitLab shared runners, self‑hosted, Jenkins, CircleCI).
3. Choose the auth mode
   Publish on supported hosted runners → trusted publishing (OIDC). Publish on non‑supported runners → granular write token with bypass 2FA. Install‑only jobs → granular read‑only token (no bypass needed).
4. Create or configure credentials
   Granular tokens are currently created in the npm web UI. For trusted publishing, set the trusted publisher for each package to the exact repo and workflow filename you’ll use.
5. Update CI secrets and configs
   Replace classic tokens stored as secrets.NPM_TOKEN or equivalent. For install‑only flows, prefer read‑only tokens and update .npmrc. For OIDC, add id-token: write permissions and remove token usage.
6. Dry run and canary
   Add a pre‑release tag (e.g., 1.2.3-rc.1) to test publish workflows safely. For install flows, run CI on a feature branch with the new secrets and --dry-run where appropriate.
7. Rotate, revoke, and document
   After success, revoke the replaced classic tokens, set calendar rotation for any write tokens (≤90 days), and document the new process for maintainers who publish locally.

How to implement in common CI systems

GitHub Actions (recommended path: trusted publishing)

If your publish jobs run on GitHub‑hosted runners, use trusted publishing to eliminate long‑lived tokens. Key moves:

• In your package settings on npm, configure a trusted publisher that points to exactly the repo and workflow filename (e.g., release.yml).
• In your workflow, grant OIDC: permissions: id-token: write. Remove NPM_TOKEN usage from steps. Keep registry auth lines for installs of private deps if needed, but those should use read‑only tokens.
• Run a canary release to verify. If validation fails, double‑check the workflow filename and that you’re using a GitHub‑hosted runner, not self‑hosted.

When trusted publishing isn’t an option (temporary or architectural), create a granular write token and enable the “bypass 2FA” flag so noninteractive jobs aren’t blocked. Scope the token narrowly to the package(s) you publish, store it as a GitHub secret, and rotate ≤90 days.

GitLab CI/CD

Trusted publishing also supports GitLab.com shared runners. The setup is similar: add a trusted publisher for GitLab in npm, then ensure your pipeline uses the configured project and workflow. For private dependency installs, use a separate read‑only token in NPM_TOKEN or an .npmrc file injected at build time.

Jenkins and other self‑hosted runners

OIDC trusted publishing isn’t supported on many self‑hosted systems today. Default to tokens—but be smart:

• Create read‑only tokens for install‑only jobs and inject via credentials providers. Keep them out of images and logs.
• For publish jobs, use granular write tokens with bypass 2FA enabled, scope to the specific package(s), set a rotation job every 60–80 days, and alert on failures.
• Block outbound logs from printing npm auth. Mask env vars and sanitize verbose installers.

CircleCI and others

Same pattern as Jenkins: prefer read‑only tokens for installs, write tokens with bypass for publishes, and tighten scope. In all cases, treat NPM_TOKEN as a per‑project secret, not an org‑wide magic value.

“People also ask” quick answers

Do I need to enable bypass 2FA for CI?

Only if your CI workflow needs to write (publish or modify data) using a granular token. Install‑only flows don’t require bypass. OIDC trusted publishing doesn’t need tokens or bypass at all.

Will read‑only tokens break on Nov 19?

Classic tokens of any kind break on Nov 19. Granular read‑only tokens continue working, but plan for their normal rotation. If you’re unsure which type you have, check the token’s properties in npm settings.

Is trusted publishing required?

No—but it’s the healthiest long‑term path. It removes the blast radius of long‑lived write tokens and adds provenance. If your pipelines run on supported hosted runners, make the switch now and remove token complexity.

How do I install private packages in CI after the migration?

Use a granular read‑only token dedicated to installs. Inject it at runtime and configure .npmrc with //registry.npmjs.org/:_authToken=${NPM_TOKEN}. Avoid reusing publish tokens for installs.

A pragmatic two‑track plan for the next 10 days

Here’s how I’d sequence work for a mid‑size org with many repos:

1. 48 hours: Freeze on publishing changes. Inventory all usage, classify, and decide auth modes. Create trusted publishers and the minimum set of read‑only tokens you need.
2. Days 3–5: Migrate install‑only pipelines first; they’re low‑risk, high‑volume. Then move publish jobs with the simplest path to OIDC (GitHub/GitLab hosted runners). Canary releases in each product line.
3. Days 6–7: Mop‑up—self‑hosted runners and edge cases. Apply write tokens with bypass where OIDC isn’t possible yet. Add rotation reminders and observability around publish steps.
4. Days 8–10: Documentation, runbooks, and game day. Revoke remaining classics. Enforce 2FA across maintainers. Schedule a Nov 19 watch window with on‑call coverage.

Security hardening you shouldn’t skip

Migration is the perfect excuse to raise the floor:

• Enforce 2FA org‑wide for maintainers, with FIDO keys recommended. This aligns with local publishing’s new behavior and stops account‑takeover pivots.
• Scope every token to the packages and actions required. Don’t hand a monorepo token rights to unrelated registries or projects.
• Short‑lived everything: Session tokens for local publishes are here; mirror that ethos by rotating any remaining write tokens on a predictable cadence.
• Secrets hygiene: Mask and restrict. Ban printing npm config in CI logs. Validate your container base images don’t bake in .npmrc.
• Observability: Add alerts for failed publishes, unexpected 401/403 from the registry, and unusual token use outside release windows.

Real‑world gotchas I keep seeing

Three patterns bite teams the week of a migration:

• Mismatched workflow filenames in trusted publishing. The registry validates against the calling workflow’s filename—typos break auth. Standardize your release workflow name across repos.
• Self‑hosted illusions. Folks assume OIDC will Just Work™ everywhere. If your provider isn’t supported, plan for tokens now and revisit OIDC later.
• Read tokens doing write work. Failing installs hide a deeper issue: a job also publishes nightly snapshots or tags. Separate concerns: one pipeline for install/test, another for publish with the least required rights.

Where Bybowu can help

If you want a battle‑tested sequence for complex orgs, our team has published detailed guides you can drop into your runbook. Start with the CI/CD cutover guide for npm token migration, then use the last‑mile npm migration playbook to chase edge cases. If you’re on GitHub, pair that with what to change in GitHub Actions this month so runners, secrets, and policies are aligned.

Need hands‑on help for an enterprise cutover? Scope it with us via Bybowu services and we’ll resource a short‑burst engagement, or reach out directly on the contact page for a time‑boxed migration sprint before November 19.

What should local maintainers do?

Publishing from a laptop? Expect two changes on or before Nov 19:

• 2FA prompts for writes if you’re using tokens or passwords. Make sure maintainers are enrolled and have backup codes or hardware keys.
• Session tokens (~2 hours) for local publishes. Plan your release process accordingly; don’t assume all‑day tokens. Use your CI for official releases where possible and keep local publishes for urgent hotfixes.

Pro tip: shift routine releases to CI with OIDC. It’s faster, safer, and auditable. Keep human‑in‑the‑loop only for versioning approvals.

Sample configurations to copy

Trusted publishing in GitHub Actions

Add OIDC and remove token usage in your publish job:

permissions:\nid-token: write\ncontents: read

Then run your usual build and npm publish. The CLI will use the OIDC exchange automatically when the package’s trusted publisher matches the repo and workflow.

Install private packages with a read‑only token

Inject NPM_TOKEN as a secret and use a project‑scoped .npmrc template at build time:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}\nalways-auth=true

Keep this token read‑only. Don’t reuse publish creds for installs.

What to do next (today, not tomorrow)

• Run the 30‑minute inventory: find classic tokens in secrets, .npmrc, and container builds.
• Move publish jobs on GitHub/GitLab hosted runners to trusted publishing. Canary a pre‑release today.
• Downgrade install‑only pipelines to read‑only granular tokens. Remove write scopes you don’t need.
• For non‑supported runners, create scoped write tokens with bypass 2FA and set rotation reminders.
• Book a Nov 19 watch window and revoke any straggler classics ahead of the cutoff.

Zooming out

This migration is the right direction. Long‑lived write tokens have been the soft underbelly of JavaScript supply chains for years. With granular scopes, 90‑day lifetimes, enforced 2FA, and OIDC for publishes, you reduce the blast radius of inevitable credential mishaps. The trick is sequencing the work so you don’t torch velocity. Use the checklist above, keep changes small and reversible, and you’ll sail through November 19.

If you want more detail or a second set of eyes, our blog and migration guides have copy‑paste snippets and runbooks you can adapt. And if Nov 19 is too close for comfort, we can jump in on short notice to steady the ship.