npm Token Migration: Beat the Nov 19 Cutoff

Let’s be blunt: npm token migration is not optional anymore. On Wednesday, November 19, 2025, the registry will revoke classic tokens and short‑circuit long‑lived local publishing sessions. If your pipelines still lean on a copy‑pasted secret from 2019, expect your next npm publish to face‑plant. The good news: you can cut over in a day, keep velocity, and actually improve your supply‑chain posture.

What changes on Nov 19—dates, behaviors, and blast radius

Here’s the short, dated version. Since November 5, new classic tokens can’t be created anywhere (site, CLI, API). Existing classics keep working only until November 19, 2025, when they’re permanently revoked. New write‑capable granular tokens enforce 2FA by default. Write‑scoped granular tokens now have a hard 90‑day maximum lifetime. Meanwhile, local publishing with long‑lived tokens is being replaced by short session credentials—think hours, not months.

Practically, that means three immediate risks for engineering teams:

• A failing publish step when a classic token is pulled from secrets.NPM_TOKEN.
• Human‑driven releases stalling on 2FA prompts unless you explicitly configure a CI bypass or move to OIDC.
• Silent drift where granular tokens expire on a schedule you didn’t plan for, breaking pipelines mid‑sprint.

Why this is happening (and why it’s good for you)

Supply‑chain incidents over the past year forced registries to clamp down. Attackers love broad, long‑lived credentials sitting in build systems. Shortening lifetimes, enforcing modern 2FA, and favoring identity‑based publishing (OIDC) reduce blast radius dramatically. It’s not performative theater; it’s the same design pattern cloud providers used to kill static credentials in favor of short‑lived role assumptions.

Pick your lane: granular token or OIDC trusted publishing?

There are two viable paths. Both are better than the status quo.

Lane A: Granular access tokens for CI

Granular tokens let you scope permissions to specific packages or orgs with an enforced expiry. For noninteractive builds that truly require a token, you can enable the CI‑friendly “bypass 2FA” flag on a write token. It’s familiar, quick to deploy, and a decent bridge if you’ve got complex private registry flows. The catch: you have to rotate routinely, and you’re still storing a secret in your CI. Treat it like a temporary stepping stone.

Lane B: OIDC trusted publishing

With OIDC trusted publishing, your workflow presents a signed identity token to npm, which exchanges it for a short‑lived registry credential. No npm token is stored in CI. Every publish is tied to a specific repository and workflow filename that you authorize in npm package settings. You also get provenance attestations by default on supported setups. The catches: you must run on supported cloud‑hosted runners (GitHub Actions or GitLab.com shared runners today), and you need to get the configuration details exactly right.

If you’re already on GitHub Actions, choose OIDC unless you have a blocker like self‑hosted runners that can’t move yet. It’s safer, it’s cleaner, and it eliminates a whole class of secret‑leak incidents.

The fast path: a 7‑step cutover plan that works

Below is the exact sequence we’ve used with product teams this week to get from “classic token in a secret” to resilient publishing.

1) Inventory everything that touches npm

Search your CI config and infra for npmrc setup, NPM_TOKEN, or registry overrides. Watch for poly‑repo quirks: a separate docs or example app pipeline might publish canary builds you forgot about. If you ship multiple packages, note which ones need write access and which only read private dependencies.

2) Decide lane per pipeline

For each publishing pipeline, pick Lane A (granular token) or Lane B (OIDC). For read‑only install jobs that only pull private packages, use a read‑scoped granular token on a short rotation and keep it out of publish steps. For the one pipeline that actually runs npm publish, prefer OIDC.

3) If choosing OIDC, wire the trust correctly

In npm package settings, add a Trusted Publisher and point it to the exact GitHub org/repo and the workflow filename that runs npm publish. In your workflow, set:

permissions:
  id-token: write
  contents: read

Run on a GitHub‑hosted runner (or GitLab.com shared runner). Update to npm CLI 11.5.1+. Keep tags‑based triggers for release workflows; they’re predictable and less abuse‑prone. If the first publish fails with “Unable to authenticate”, triple‑check the filename matches what you configured in npm—case sensitive, including the .yml extension.

4) If choosing granular tokens, scope and rotate

Create a new granular token via npm’s website. Give it the smallest scope possible: package‑level access if you can, write only where publish happens, read everywhere else. Set an expiration that fits your rotation rhythm, understanding write tokens won’t exceed 90 days. Enable the CI bypass for 2FA only on the specific write token used by the publish job. Store it in your CI secret manager and only mount it in the publish job.

5) Make the workflow change small and surgical

Keep your first PR tight. Swap the token source or add id-token: write, upgrade npm, and stop there. Resist the urge to refactor the entire pipeline mid‑migration. You want one thing to test: publishing.

6) Dry‑run, then ship a canary

Use npm publish --dry-run first to make sure your build artifacts are shaped correctly. Then tag a canary like v1.2.3-canary.0 to exercise the full release flow. Verify provenance shows up for public packages when using OIDC. If you rely on prepublishOnly or postpublish scripts, confirm they still run—some orgs disable scripts during CI publishes for safety; your action or workflow may specify --ignore-scripts.

7) Delete old tokens and commit to a rotation rhythm

Once you see a successful publish, revoke any lingering classic tokens and stale granular tokens. If you stuck with granular tokens, book a rotation cadence on the calendar. If you moved to OIDC, enjoy the silence—no more token rotations for that workflow.

People also ask

What exactly happens on November 19, 2025?

Classic tokens are revoked and long‑lived local publishing flows are replaced with short sessions. If your build relies on a classic token, authentication fails immediately. If you publish from a laptop without planning for 2FA or sessions, you’ll hit prompts or expiration windows you didn’t anticipate.

Do I need OIDC, or can I keep granular tokens?

You can keep granular tokens, but you’ll be on a rotation treadmill and still managing secrets. OIDC removes the stored secret and ties publishing to a specific, approved workflow. Most teams on GitHub Actions should make OIDC the default and use granular tokens only where OIDC isn’t supported yet.

Will OIDC work on self‑hosted runners?

As of today, trusted publishing supports GitHub‑hosted runners and GitLab.com shared runners. If you’re locked to self‑hosted for compliance, use granular tokens for now, scope tightly, and monitor for future support.

What breaks with private dependencies?

Trusted publishing only covers npm publish. If your build needs to npm ci private packages, you still need a read‑scoped token for installs (short‑lived and narrowly scoped). Don’t give your install token publish rights.

Operational guardrails: avoid the common foot‑guns

• Workflow filename mismatches: Your trusted publisher entry must match the workflow’s filename exactly, not a display name.
• Multi‑repo or monorepo confusion: If multiple packages publish from different workflows, each package needs its own trusted publisher configuration. Don’t assume one setting covers them all.
• Org‑wide 2FA policies: Some org policies enforce hardware‑key 2FA. That’s good. Document recovery paths for release managers so a lost key doesn’t block urgent security patches.
• Install vs publish credentials: Keep read tokens for installs and OIDC for publish. Mixing scopes is how secrets leak into logs, containers, and caches.
• Environment pinning in Actions: If you use protected environments, remember your publish job’s effective ref and environment rules; PR workflows behave differently than default‑branch workflows. We covered those nuances in our GitHub Actions November 2025 checklist.

Decision matrix: which option fits your reality?

When advising teams, I use a simple three‑question filter.

1) Are you on GitHub Actions or GitLab.com shared runners for release builds? If yes, prefer OIDC.
2) Do you need provenance and minimal secret sprawl? That’s OIDC again.
3) Are you stuck on self‑hosted runners or a vendor not yet supported? Use granular tokens now, with a plan to migrate later.

If you answered OIDC twice, stop debating. Do the change this week.

Reference implementation: a minimal OIDC workflow

Here’s a clean, durable pattern that publishes on version tags. It plays well with semantic‑release, changesets, or a manual tagging step.

name: publish

on:
  push:
    tags:
      - 'v*'

permissions:
  id-token: write
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'
      - run: npm install -g npm@latest
      - run: npm ci
      - run: npm test --if-present
      - run: npm publish

On the npm side, configure the trusted publisher to this repository and the workflow filename publish.yml exactly. If you must support a monorepo of many packages, consider a dedicated publish-* workflow per package to keep trust mappings simple and auditable.

Security wins you can measure

• Credential lifetime drops from months to hours: OIDC exchanges produce short‑lived tokens per run. Even if a build log leaks, reuse is unlikely and time‑boxed.
• Scope is explicit: Trusted publishing binds to a repo and workflow file; granular tokens bind to packages or orgs. Either way, accidental broad access is harder.
• Provenance by default: On supported setups, your publishes emit provenance, making downstream verification and SBOM tooling more useful during audits.

Edge cases and how to handle them

Self‑hosted runners with air‑gap: Until trusted publishing supports self‑hosted, use granular tokens plus strict secret‑mounting controls. Mirror artifacts into the air‑gap and run a separate publishing job that’s allowed to touch the internet.
Private packages with public source or vice versa: OIDC provenance won’t appear if the source repository is private. That’s normal. Don’t chase ghosts.
Manual hotfixes from laptops: If you must publish locally, be ready for session‑based prompts and modern 2FA. Keep a hardware key handy and plan a short, documented local release path with approvals.

Let’s get practical: a pre‑deadline checklist

Print this, check boxes, sleep better.

• Audit all repos for NPM_TOKEN and _authToken in .npmrc.
• For each publish job, pick OIDC or granular.
• If OIDC: configure trusted publisher, add id-token: write, upgrade to npm 11.5.1+, and publish a canary tag.
• If granular: create write token with CI bypass, set short expiry, scope to the exact package, rotate calendar invites for owners.
• Remove classic tokens from secrets. Revoke them in npm settings.
• Add a pipeline guard: fail hard if NPM_TOKEN is referenced in publish jobs after cutover.
• Create a one‑pager in your repo’s /docs/releasing.md with screenshots and the tested workflow filename.

Related playbooks if you want the longer version

If you want a deeper, step‑by‑step walkthrough for time‑boxed teams, grab our one‑week npm token survival guide and the final 7‑day cutover plan. If your release process also relies heavily on GitHub Actions environments or reusable workflows, sanity‑check those too with our November 2025 Actions fixes.

SEO corner: what people search and what they really mean

If you’re skimming search results for “npm token migration”, you’re probably trying to answer three things fast: will my publish break, what’s the easiest safe fix, and how do I avoid doing this again next quarter. The answers: yes if you do nothing; OIDC is the easiest safe fix on GitHub‑hosted or GitLab‑hosted runners; and you avoid the redo by deleting every token you don’t absolutely need and binding publishing to a single, auditable workflow.

What to do next—today

• Choose OIDC for publishing pipelines on supported runners; use granular read tokens for installs.
• Ship a canary release from the new workflow by end of day.
• Revoke all classic tokens right after a successful canary.
• Calendar a quarterly security review for token scopes/expirations—then make it boring with OIDC.

If you need an extra set of hands to review your pipeline, reach out via our services page or drop a note on our contacts form. This is the rare security change that also makes life easier. Take the win this week.

The bottom line

Classic tokens had a good run; attackers liked them even more. With this npm token migration, the safer defaults finally line up with how we already deploy to clouds: short‑lived credentials, explicit trust, and automation by design. Do the minimal changes now, test with a canary, and you’ll sail past November 19 without drama—while ending the year with a stronger, simpler release system.