npm Token Migration: The Final Week Playbook

Let’s get straight to it: if your pipelines still rely on classic credentials, npm token migration is now a last‑mile priority. On November 19, 2025, classic npm tokens are revoked. CI builds that publish with an old NPM_TOKEN will fail. The good news: you can execute a clean cutover this week—without risky refactors—by choosing the right path (granular tokens or OIDC trusted publishing) and running a focused set of tests.

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

You only need a few facts to plan with confidence:

• Nov 5, 2025: Creating new classic tokens was disabled across website, CLI, and API. Existing classic tokens keep working only until Nov 19.
• Granular access tokens: New write‑scoped tokens now enforce 2FA by default, there’s an optional Bypass 2FA flag for CI/CD, and existing write tokens are capped at a 90‑day maximum lifetime. Any token set to expire after February 3, 2026 was adjusted to that date.
• Nov 19, 2025: All classic tokens are revoked. For local/manual publishing, long‑lived local tokens are replaced with short‑lived 2‑hour session tokens.

Two more context points matter for teams: (1) new granular write tokens typically default to short lifetimes, forcing rotation discipline; (2) npm is steering maintainers toward trusted publishing with OIDC so you don’t store long‑lived write tokens at all.

Who gets hit hardest?

Patterns we’re seeing in audits:

• Release pipelines that publish from GitHub Actions with a repository or organization secret named NPM_TOKEN.
• Mono‑repos using a single token to publish multiple packages via a workspaces script.
• Internal packages where a classic token was reused across multiple orgs or private registries.
• Local release scripts that assume an always‑valid token in a developer’s CLI config (~/.npmrc).

If any of the above describe your setup, make time for a rehearsal publish before the 19th.

Your decision tree: granular token vs. trusted publishing (OIDC)

Here’s the thing: both paths work, but the right choice depends on your constraints.

If you need the lowest operational overhead

Pick trusted publishing (OIDC). You authorize a specific workflow in your CI to publish on behalf of your package. Each publish uses a short‑lived identity token minted by your provider, not a reusable write token. No rotation. No secret to leak. This is the steady‑state most teams should target.

If you can’t switch to OIDC this week

Use a granular access token as a bridge. Scope it narrowly to the package or org, enable Bypass 2FA only for the workflow that needs to publish, and schedule rotation at or below 90 days. It’s not as elegant as OIDC, but it’s a pragmatic stopgap you can deploy quickly.

One caveat teams occasionally hit: for a brand‑new package that doesn’t exist yet, you may need to bootstrap with a one‑time token before enabling OIDC on that package. Plan around that edge case by publishing the initial 0.0.1 manually, then flipping to OIDC.

The npm token migration checklist (printable)

Work through these steps in order. Most orgs can finish in a day.

1. Inventory where tokens live. Search repos, org secrets, and deployment systems for NPM_TOKEN, //registry.npmjs.org/ lines in .npmrc, and any npm publish steps. Don’t forget release scripts in package.json and build tools.
2. Choose your target: OIDC trusted publishing (preferred) or granular token (bridge).
   • OIDC: confirm your CI provider supports npm’s trusted publishers and that you can edit package settings.
   • Granular token: confirm who owns the npm org/package and who can generate a token with the right scope.
3. Prepare your npm config. Remove any hard‑coded auth lines like //registry.npmjs.org/:_authToken=... from .npmrc committed to the repo. Prefer environment injection at runtime or OIDC.
4. Wire up OIDC trusted publishing (recommended).
   • In npm, enable trusted publishing for the package and authorize the workflow from your CI (e.g., a GitHub Actions workflow in a specific repo).
   • In your workflow, ensure permissions: id-token: write and use actions/setup-node with registry-url for npm. The npm CLI will detect OIDC and mint a short‑lived token for the publish.
   • Run a dry‑run job that executes npm publish --dry-run to validate auth and provenance without releasing.
5. Or create a granular token (bridge).
   • Generate a granular access token scoped to the specific package or org with publish permissions, minimal scope, and a short lifetime. If CI needs noninteractive publishing, enable the Bypass 2FA checkbox.
   • Store it as a secret in your CI (e.g., NPM_TOKEN at the repo level), and inject it only in the publish job.
   • Set a calendar reminder or a bot job to rotate before expiry. With the 90‑day cap, treat rotation as mandatory hygiene.
6. Rehearse a full publish. Create a prerelease tag like 1.2.3-rc.0, run the pipeline end‑to‑end, and verify the package appears on npm with provenance attached. Roll back by unpublishing the prerelease if needed.
7. Remove any classic tokens. Delete old secrets after you’ve confirmed the new path works. Fewer credentials, less risk.
8. Document the new workflow. Update your contributor guide so maintainers know how releases happen, who can trigger them, and how tokens are rotated (if you’re still on the bridge).

GitHub Actions changes this month you should fold in

Two more changes are worth baking into your plan because they can produce “mysterious” CI failures the same week your tokens change:

• macOS 13 brownouts: Jobs using macos-13 may temporarily fail during scheduled windows on Nov 11, Nov 18, and Nov 25 (14:00–00:00 UTC). The image retires on Dec 4. Update labels to macos-15 or macos-latest (arm64 preferred) and move Intel‑only steps to Linux when possible.
• M2 macOS runners are generally available, and reusable workflow limits increased (up to 10 levels nested and 50 calls total). If you’re refactoring pipelines anyway, now’s the time to address performance and composability.

For a detailed runbook on those CI updates, see our breakdown in GitHub Actions: November 2025 Changes That Matter and the follow‑up on limits and new runner options in New Limits, M2, Agent.

People also ask: fast answers for busy teams

What happens to my NPM_TOKEN secret on November 19?

If it’s a classic token, publishes will return a 401/403 and your release job will fail. Replace it with either a granular token or OIDC trusted publishing before that date.

Do my existing granular tokens stop working?

No, they keep working, but write tokens are capped at a 90‑day maximum lifetime. Check expirations and plan rotation so you don’t hit a surprise in Q1 2026.

Do I need 2FA for CI?

For CI using granular tokens, you can enable Bypass 2FA on that token specifically. With OIDC trusted publishing, you don’t manage 2FA for the CI flow because npm trusts the workflow identity rather than a reusable token.

What about local/manual publishes by maintainers?

Local publishing moves toward short‑lived session credentials and 2FA. Expect to use your WebAuthn/passkey more often. That’s by design; it reduces the blast radius of compromised desktops.

Is OIDC trusted publishing enough on its own?

Yes for most cases, and it’s the long‑term recommended route. One noted limitation: the very first publish of a brand‑new package may require a one‑time manual token before you can enable OIDC for that package.

Edge cases and gotchas to check now

These are the sharp edges that trip teams during migration week:

• Provenance settings: If your org enforces provenance, make sure your new path (OIDC or granular token) still emits a valid attestation. Use npm publish --provenance from CI with OIDC.
• Multi‑package repos: Don’t mint a single write token that covers dozens of packages. Either enable OIDC per package or create one token per scope with the narrowest permissions possible.
• Private registries: If you mirror npm or use a Verdaccio proxy, confirm auth flows still pass through correctly. You may need separate auth for upstream publish vs. internal read.
• Initial publish: Plan a one‑time human publish for new packages before flipping to OIDC.
• CLI versions: Keep your release runners on a recent npm version so trusted publishing and provenance flags behave as expected.
• Config drift: Remove legacy .npmrc lines from the repo. Inject tokens at runtime only in the job that needs them.

A practitioner’s rehearsal: 45‑minute cutover

Here’s a compact plan I’ve used with clients this week.

1. Create a feature branch called release‑pipeline‑migrate.
2. Switch to OIDC: add permissions: id-token: write, run actions/setup-node with registry-url: https://registry.npmjs.org, and remove any auth token from the workflow.
3. Enable trusted publishing on the package and authorize your workflow.
4. Push a prerelease with npm version prerelease --preid=rc and npm publish --dry-run first. If the dry run passes, remove --dry-run and publish the RC.
5. Verify in npm that the RC exists and provenance is attached. Promote or unpublish as appropriate.
6. Delete any classic tokens in repo/org secrets and in maintainers’ local .npmrc.
7. Document and merge the workflow changes.

If OIDC isn’t feasible today, swap step 2–4 with a granular token scoped to a single package, Bypass 2FA checked, and a rotation reminder set. Then plan a second pass to graduate to OIDC.

Metrics and monitors to add this week

Don’t wait for a pager. Add simple monitors so you spot auth drift early.

• Publish job exit codes: Alert on any status change for your release workflow.
• npm API response codes: Parse logs for 401/403 from registry.npmjs.org and send a Slack alert with the failing package name.
• Token expiry dashboards: If you remain on granular tokens, store expirations in a small table or in repo metadata and warn at T‑14 days.

Why this is happening—and why the direction is good

September and October brought a string of supply‑chain incidents that abused stolen credentials and CI workflows. Shortening token lifetimes, enforcing 2FA for manual publishing, and moving CI to OIDC reduces the chance a leaked token becomes a months‑long backdoor. Is weekly rotation annoying? Sure. But the end state—no long‑lived write tokens at all—is both safer and simpler to operate.

What to do next (developers)

• Run the inventory search for NPM_TOKEN and .npmrc hints in your repos today.
• Pick your target: OIDC now, or granular token as a bridge with a scheduled rotation.
• Rehearse a prerelease publish and verify provenance.
• Delete classic tokens; update runbooks and contributor docs.
• >

What to do next (engineering managers)

• Assign an owner for each package with a hard deadline before Nov 19.
• Track cutover status on a single checklist. Require a green RC publish before merge.
• Tie this work to CI modernization: update macOS runner labels, adopt reusable workflows under the new limits, and capture the performance wins from M2 runners.
• Schedule a post‑mortem‑style retro next week to remove the bridge tokens and finish the OIDC migration.

Related playbooks from our team

If you’d like deeper step‑by‑steps, we’ve published focused guides you can hand to the team:

• Everything to fix by Nov 19 (shortlist of misconfigurations and where they hide)
• What will break on Nov 19 (CI, local, and monorepo scenarios)
• The Nov 19 cutover playbook (minute‑by‑minute rehearsal)
• GitHub Actions November 2025: Changes That Matter (brownouts, runners, limits)

Final thought

This migration isn’t busywork; it’s a turning point. After next week, the healthiest npm pipelines won’t carry persistent write power at all. Use this moment to remove secrets from your CI, adopt trusted publishing, and make releases boring again. If you need help auditing or accelerating the cutover across a portfolio, our team does this work every day—see what we ship on our portfolio and how we approach migrations on what we do.