npm Token Migration: Your Final 7‑Day Cutover Plan

If you maintain JavaScript packages, the npm token migration just moved from “we’ll get to it” to “we ship or we slip.” On November 19, 2025, all classic npm tokens will be permanently revoked. New classic tokens were already disabled on November 5, and granular token rules tightened the same day. If your CI/CD still runs npm publish with a long‑lived token, plan for breakage unless you cut over this week. (github.blog)

The npm token migration: what changed and when

Two dates matter. First, on November 5, 2025: classic tokens could no longer be created; granular tokens with write access began enforcing 2FA by default; and their lifetimes were capped, with existing long expirations pulled forward. Second, on November 19, 2025: every remaining classic token will be revoked, and long‑lived local publishing tokens will be replaced by short session tokens. GitHub emphasized these are npm token changes, not GitHub token changes. (github.blog)

In parallel, npm’s trusted publishing via OIDC is now generally available. With it, GitHub Actions or GitLab CI/CD can publish without storing an npm token at all. This requires npm CLI 11.5.1 or later and a one‑time configuration on npmjs.com. Provenance is emitted automatically with trusted publishing, tightening your supply‑chain story by default. (github.blog)

Who breaks next week—and why

Any repo that does one of the following is at risk: stores NPM_TOKEN as a repository or organization secret; uses third‑party publish actions that expect a token; or depends on a long‑expiration write token in self‑hosted release scripts. Once the revocation lands on November 19, npm publish will fail authentication, often mid‑release, with confusing logs. The fix isn’t just swapping tokens; the secure path is OIDC-based trusted publishing. (github.blog)

Let’s get practical: a 90‑minute CI cutover

You can complete a clean migration in a single focused session. The steps below assume GitHub Actions. GitLab users can follow a similar path—the core idea is the same: you trade long‑lived tokens for short‑lived OIDC assertions that npm accepts only from your authorized workflow. (docs.npmjs.com)

Option A (recommended): Trusted publishing with OIDC

Step 1: Confirm your npm version in CI is >= 11.5.1. If you’re using actions/setup-node@v5 with Node 20/22/24, you’re likely current. (docs.npmjs.com)

Step 2: In your GitHub workflow, add minimal permissions: permissions: contents: read and id-token: write. This enables OIDC token exchange during publish without exposing registry tokens. (docs.npmjs.com)

Step 3: On npmjs.com, open your package’s Settings and add a Trusted Publisher. For GitHub, you’ll specify org/user, repository, workflow filename, and (optionally) an environment name. Save it. (github.blog)

Step 4: Remove token: inputs from publish steps and call npm publish normally. When OIDC is detected, the CLI authenticates without an npm token and emits provenance automatically. (github.blog)

Gotchas: If the workflow filename doesn’t match the configuration on npmjs.com exactly—including case and .yml—publishes will fail. Trusted publishing currently supports only GitHub‑hosted or GitLab.com shared runners; self‑hosted runners aren’t supported yet. (docs.npmjs.com)

Option B (stopgap): Granular tokens with guardrails

If you can’t switch to OIDC this week, create a granular token with tightly scoped write access and a short expiration, enable the CI 2FA bypass for that token, and rotate it on a schedule. This keeps releases moving, but it’s a temporary bridge—not your destination. (github.blog)

People also ask: do I need 2FA in CI?

Short answer: not directly. With trusted publishing, the CI proves its identity via OIDC, so there’s nothing to enter. With granular tokens that have write permissions, npm enforces 2FA by default; you must explicitly enable the CI bypass on the token or you’ll hit prompts you can’t satisfy in automation. (github.blog)

Can I publish the first version of a brand‑new package with OIDC?

Today, there’s a known limitation: the initial publish typically requires a token because you can’t configure trusted publishing until the package exists in npm settings. Many teams do the initial 0.0.1 with a short‑lived granular token, then switch to OIDC for all subsequent releases. Track the upstream request to remove this limitation. (github.com)

What about private dependencies in CI?

Trusted publishing covers the npm publish operation. Installs for private dependencies in your build still need a read‑only token or equivalent auth. Keep a separate, least‑privilege read token for npm ci, distinct from publishing. (docs.npmjs.com)

Heads‑up: GitHub Actions changes land on December 8

There’s another footgun on the horizon. On December 8, 2025, GitHub is changing how pull_request_target and environment branch protections are evaluated. After that date, the workflow source and checkout commit for pull_request_target always come from the default branch, reducing surprise execution of code from contributor‑controlled branches. If your automations rely on today’s edge behaviors, re‑test now. (github.blog)

If you’re still using pull_request_target to grant secrets for forked PRs, consider safer patterns: use workflow_run from a trusted branch; gate privileged jobs behind manual approvals; or adopt per‑environment approvals with no secrets on PR events. For a deep dive on the December change and migration patterns, see our cutover guide. Review safe alternatives to pull_request_target.

Runner image removals that quietly break builds

Earlier this month, GitHub’s hosted images began removing aging toolchains. On macOS runners, Node.js 18, Android NDK 26, GCC 12, and the Ruby 3.1 toolcache started dropping on November 3, with rollout over several days. Ubuntu and Windows images are also removing Node 18 and Ruby 3.1. If your pipeline implicitly depended on these, you may see failures right as you’re migrating tokens. Pin supported versions with actions/setup-node and friends. (github.com)

A simple field checklist for the week

Use this as your stand‑up agenda and commit to shipping it before Friday.

• Inventory: Find every workflow that runs npm publish (search your org for npm publish, npm-publish, and NPM_TOKEN).
• Decide path: Prefer OIDC trusted publishing; otherwise create a minimal‑scope granular token with an expiration date you can live with.
• Harden CI permissions: Set permissions: contents: read and id-token: write on publishing workflows. Remove unused secrets.
• Configure trusted publisher: Add your repo and workflow filename in npm package settings; match case and file extension.
• Provenance: Keep the default on; verify the attestation shows up for your next release.
• Test a dry run: Use a prerelease tag (next) or a canary package name to validate end‑to‑end before your next real release.
• Pin toolchains: Explicitly set Node 20/22/24 in Actions; stop assuming Node 18 exists on hosted runners.
• Re‑audit PR automation: Remove secrets from pull_request and pull_request_target jobs; adopt approvals or workflow_run where needed ahead of December 8.

For a more granular task list you can paste into an issue, grab our accelerated playbook: Everything to fix by Nov 19.

Decision framework: which path is right for you?

Here’s how I advise teams:

If you publish from GitHub-hosted runners and your packages already exist in npm, go OIDC now. It’s strictly less risk than token sprawl, it gives you provenance, and it aligns with where registries are going. If you run on self‑hosted runners or you’re shipping a brand‑new package, use a tight granular token for the initial publish, then flip to OIDC as soon as the package appears. If you’re an enterprise with dozens of packages, standardize a template workflow with id-token: write, a single approved environment, and a consolidated set of package settings your release managers can verify quickly. (docs.npmjs.com)

What this means for security and compliance

Trusted publishing replaces a secret you could accidentally leak with a short‑lived proof of identity that’s tied to a specific workflow file. Attackers can’t exfiltrate what isn’t there, and provenance gives downstream consumers confidence in your build source. That’s a rare win‑win: better security with less toil. Independent coverage echoes the rationale: the npm ecosystem is tightening authentication after a run of supply‑chain incidents, and registries are converging on OIDC and provenance by default. (techradar.com)

Real‑world timeline: anchor your plans

Mark the dates: November 19, 2025—classic token revocation; December 8, 2025—GitHub Actions pull_request_target changes. Build your internal comms backward from those dates: merge the OIDC workflow by Wednesday, dry run by Thursday, release on Friday, and spend early next week deleting old tokens. If something slips, the granular token stopgap buys you a small window, but schedule the OIDC flip before month‑end. (github.blog)

Example architecture that scales

At org scale, I like one reusable publish workflow in .github/workflows/publish.yml, called via workflow_call, with strict permissions and a guarded environment. Each package repo calls it with inputs for tag/access. On npm, each package lists that workflow as its trusted publisher. That gives you one surface to audit and one place to rotate Node versions when runner images change. It also avoids a sprawl of slightly different publish steps across dozens of repos. (docs.npmjs.com)

What to do next (developers)

Today: PR the OIDC permissions and remove NPM_TOKEN from your publish job. Configure the trusted publisher on npm. Tomorrow: canary publish to a non‑critical tag. This week: ship a normal release through the new path, then delete unused write tokens from org secrets. Next week: review PR workflows ahead of December 8 and pin Node versions explicitly. If you need a companion checklist, our team prepared a last‑mile guide. Use this last‑mile cutover guide.

What to do next (engineering managers)

Mandate OIDC as the default for npm publishing, with exceptions documented. Track progress with a simple report: count of repos still referencing NPM_TOKEN, count of packages with trusted publisher set, and count of workflows with id-token: write. Schedule a 30‑minute brown bag to walk through the change once, then make it part of the team’s release template. If you want hands‑on help, see how we execute cutovers for clients and the outcomes they report. See how we run cutovers and browse a few relevant case studies in our portfolio.

Avoiding “one more surprise”

Cutovers fail when you change too many variables at once. Keep your release surface stable: pin Node versions, avoid bumping major build tools until your publishing path is green, and keep your first OIDC release small. If you’re deep in the weeds on GitHub Actions policy changes, we’ve summarized the breaking bits and safe patterns so you don’t have to. Read our Actions policy change explainer and, if you also run Apple toolchains in CI, note the macOS image and tooling churn we’ve been tracking on our blog. Stay current via our blog.

Bottom line

You have a one‑week window to finish the npm token migration and harden your pipeline. Move to trusted publishing with OIDC, keep a tight granular token only as a temporary bridge, and test now so you’re not debugging failed releases on November 19. While you’re at it, clean up your PR workflows before December 8 and pin your runtime versions so runner image changes don’t surprise you. If you need a partner to do this without burning a sprint, we’re here. Talk to our team about a fast cutover.