NPM Token Migration: Your 10‑Day CI/CD Survival Plan

As of November 5, 2025, npm tightened authentication across the registry. Classic tokens are effectively retired, and on November 19, 2025, they’ll be revoked. If you haven’t started your npm token migration, you still have time—but only if you work methodically. Below is a practical, 10‑day plan we’ve used with client teams to keep pipelines green while moving to granular tokens and trusted publishing.

What changed—and why it matters for your builds

Two dates drive your plan:

November 5, 2025 (live now): You can’t create classic tokens anymore. New granular tokens with write scope enforce 2FA by default, and write‑capable granular tokens have a much shorter max lifetime. There’s also a new Bypass 2FA toggle for noninteractive CI workflows when needed.

November 19, 2025: All classic tokens are revoked. Long‑lived local publish tokens are replaced by short session tokens. If your build, release, or publish depends on a classic token, expect breakage after this date.

For most teams, that means three workstreams: rotate tokens, convert publishes to trusted publishing (OIDC), and fix installs of private packages in CI.

npm token migration: the 10‑day plan

Use this timeline as a playbook. Compress the days if you can; the ordering still holds.

Day 1–2: Inventory and blast‑radius mapping

Start with where tokens live and what they do.

• Search your org for _authToken in .npmrc, environment variables, build logs, and repo secrets. Triage by repository and environment (local dev, CI, release).
• List every job that runs npm publish or installs private packages. Note if it’s GitHub Actions, GitLab CI, Jenkins, CircleCI, or self‑hosted runners.
• Collect token metadata from your npm account settings: type (classic vs granular), scopes, and expiration.

Tip: Flag anything that still references a classic token. Those are hard stop items before November 19.

Day 3: Choose the right auth pattern per workflow

There are only a few patterns that won’t bite you post‑change:

• Publishing public or private packages from CI: Prefer trusted publishing with OIDC. It eliminates long‑lived write tokens and gives provenance by default.
• Installing private packages in CI: Use a read‑only granular token scoped to the organization or package and the minimum registries. Keep expiration short.
• Developer laptops doing one‑off publishes: Enforce 2FA. Expect short session tokens when you publish locally; don’t rely on a long‑lived write token.

Document which repos move to OIDC for publish and which still need a read‑only token for install.

Day 4: Stand up trusted publishing (OIDC) for your first repo

Pick a representative package and wire up OIDC:

• Enable trusted publishing for the package in npm settings and point it at the exact repository and workflow file that runs npm publish.
• In GitHub Actions, set permissions: id-token: write in the workflow and use the npm CLI that supports trusted publishing. Keep your NODE_AUTH_TOKEN unset for the publish step so OIDC is used.
• Run a dry run (npm publish --dry-run) to verify everything except the final write.

Edge case to plan for: some teams still need a one‑time manual publish to create the initial package before enabling OIDC in settings. If your package doesn’t exist yet, create it once with a 2FA‑protected local publish, then flip to OIDC for all future versions.

Day 5: Convert release pipelines to OIDC at scale

Roll out to more repos. Standardize on a reusable workflow or composite action for npm version, changelog, provenance, and npm publish. For monorepos, confirm your release tool (e.g., Changesets, Lerna, Nx) supports OIDC in the publish step.

Blockers to resolve now:

• Self‑hosted runners: If they’re not supported for trusted publishing, run the publish job on a cloud‑hosted runner while keeping heavier build steps on self‑hosted.
• Provenance and artifacts: Verify that the generated attestations appear for each published version and that your consumers can validate them.

Day 6: Replace classic tokens everywhere else

For any CI job that still installs private packages, mint read‑only granular tokens with scope limited to what the job needs. Update .npmrc or your secrets manager. Remove the classic token entirely.

If your security model requires IP allowlisting for outbound egress, adopt a deterministic egress strategy. For Vercel users, Static IPs solve allowlisting for both builds and serverless functions. We wrote a practical guide to this in Vercel Static IPs for Builds: The New Allowlist Fix.

Day 7: Rotate, revoke, and log

Rotate any remaining granular tokens, shorten their lifetimes, and remove unused ones. Revoke every classic token you find. Enable audit logging for token usage where your platform offers it. Add monitors that alert when tokens approach expiration so you aren’t firefighting in 90 days.

Day 8: Chaos test your pipelines

Before you call it done, simulate the November 19 world. Temporarily disable a token or run with an empty NODE_AUTH_TOKEN to ensure publish steps rely on OIDC and install steps use read‑only tokens. Fix whatever breaks.

Day 9: Close edge cases

Corners that burn teams later:

• Artifact caching: If your CI caches ~/.npm or ~/.npmrc, make sure stale tokens aren’t being restored.
• Matrix builds and preview environments: Ensure ephemeral jobs don’t inherit write tokens via environment propagation.
• Monorepo permutations: Confirm only packages that changed are published and that every publish path is OIDC‑auth’d.

Day 10: Communicate the cutover

Send the plan and status to engineering managers and SRE. Include the November 19 date, the new golden path for publish and install, and who to contact if a pipeline fails. Update your developer portal and runbooks.

“Will my builds break?” and other quick answers

Do I need Bypass 2FA for CI?

Only if you’re still using a write‑capable granular token for npm publish. If you adopt trusted publishing, you don’t need a persistent write token or Bypass 2FA at all. For installs of private packages, use a read‑only token—no 2FA bypass needed.

Will my existing granular tokens stop working?

Tokens with write scope now have shorter maximum lifetimes. Many teams will see expirations sooner than expected, so add rotation to your platform schedule. After rotation, verify all references (secrets, .npmrc, Helm charts, Terraform vars) were updated.

Can I publish the first version with OIDC?

Often you’ll need to create the package once before enabling trusted publishing. Do a 2FA‑protected local publish to create the namespace, then switch to OIDC immediately. Document this as the only permitted manual step.

How do I install private packages in CI without write tokens?

Create a granular, read‑only token scoped to only the org or packages you need. Store it in your CI secret store and reference it in .npmrc for install steps only. Keep expiration tight and rotate automatically.

A pragmatic configuration blueprint

Here’s how a GitHub Actions workflow might look once you adopt trusted publishing for the publish job, while keeping a read‑only token for install steps:

permissions:\n contents: read\n id-token: write\n\njobs:\n release:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: actions/setup-node@v4\n with:\n node-version: 20\n registry-url: https://registry.npmjs.org\n - name: Install (private deps allowed)\n env:\n NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN_READONLY }}\n run: npm ci\n - name: Build\n run: npm run build\n - name: Publish with OIDC (no persistent token)\n env:\n NODE_AUTH_TOKEN: ""\n run: npm publish

Important details to double‑check:

• The workflow filename matches the npm package’s trusted publishing settings exactly.
• NODE_AUTH_TOKEN is not set for the publish step so OIDC kicks in.
• You’re using an npm CLI version that supports trusted publishing and provenance by default.

Security context: why this is happening

The JavaScript ecosystem absorbed several supply chain incidents this fall, including a self‑replicating worm campaign that spread via compromised maintainer accounts and post‑install scripts. The common thread: long‑lived credentials are soft targets, especially in CI where secrets can be leaked through logs, caches, or misconfigured runners. Short‑lived, workload‑bound identity and provenance are the right defaults—and they’re becoming table stakes.

Platform‑level guardrails checklist

Security leads can use this checklist to move from one‑off fixes to durable guardrails:

• Authentication: Enforce OIDC trusted publishing for every package that your org publishes. Prohibit long‑lived write tokens in pipelines.
• Token hygiene: All install tokens are granular and read‑only. Expiration is 30–90 days with automated rotation and alerts.
• Runner trust: Publish jobs run only on cloud‑hosted runners. Self‑hosted runners are isolated to non‑publish tasks.
• Network egress: If partners require allowlisting, use deterministic egress (e.g., Static IPs) for builds and functions. See our guide on Vercel Static IPs for Builds for a practical pattern.
• Provenance verification: Require consumers to verify provenance on internal packages before promotion to staging or prod.
• Secrets discipline: Block committing .npmrc with tokens to VCS. Nuke tokens from caches. Scan artifact stores for accidental leakage.
• SBOM + attestation: Generate SBOMs and attach build attestations; fail the gate when anything is missing or unsigned.

Operational pitfalls we’ve seen—and how to avoid them

Accidentally restoring old tokens from cache: Clear ~/.npmrc and any cache keys that include credentials during the cutover. Consider writing .npmrc on the fly in CI from a template.

Monorepo publish order pain: With OIDC, ensure your release tool supports topological publish and retries when registry propagation lags.

“Why is local publish failing?”: From November 19 on, expect short session tokens for local 2FA‑protected publishes. Document the new flow and discourage local publishes for anything except emergency hotfixes.

Two registries, one token: Don’t. If you consume both npmjs and a private registry, use separate tokens and keep scopes minimal.

Where this intersects your stack

Frontend teams on Next.js or Angular, backend Node services, design system packages, and internal CLI tools all hit the registry daily. If you’re running Next.js 16 upgrades, schedule token work alongside routing and caching changes. We broke down the v16 platform shifts in Next.js 16 Ships: Cache, Proxy, and Your Plan, which pairs well with the auth changes you’re making now.

If your platform team is juggling agent‑driven workflows and security posture, we’ve also published actionable guidance on GitHub’s new agent capabilities. See GitHub Agent HQ: The November 2025 Rollout Playbook for a parallel migration mindset.

What to do next

• Run the 10‑day plan starting today. Put November 19, 2025 on your engineering calendars.
• Move publishes to OIDC trusted publishing. Kill long‑lived write tokens.
• Swap private‑install auth to read‑only granular tokens with short expirations.
• Adopt deterministic egress if you need IP allowlists; see our Static IPs guide.
• Practice a break‑glass flow for package hotfixes under 2FA.

Need a partner to push this over the line? Our team ships these migrations for SaaS and enterprise platforms under real deadlines. See what we do on our services page or drop us a note via contact. And if you want a shorter primer on the deadline itself, we’ve got you covered with NPM Token Migration: Beat the Nov 19 Deadline.

Zooming out

Here’s the thing: this isn’t just about checking a box before a cutoff date. Token rotation, provenance, and workload identity are becoming the baseline for modern software delivery. Teams that embrace them now not only avoid outages on November 19, 2025—they reduce their attack surface and free themselves from quarterly token fire drills. Make the move once, build the guardrails, and keep shipping.