npm Token Migration by Nov 19: The CI/CD Playbook

Let’s be blunt: npm token migration is no longer a memo—it’s a deadline. As of November 5, 2025, npm disabled creation of classic tokens and tightened behavior for write-enabled granular tokens. On November 19, 2025, classic tokens will be revoked, and long‑lived local publishing tokens become short two‑hour session tokens. If you don’t move, your next publish can fail—and your attack surface stays wide open. (github.blog)

Here’s the thing…this isn’t just a housekeeping chore. The changes follow real incidents—most notably the Shai‑Hulud worm that compromised 500+ packages by stealing maintainer credentials and propagating across repos and CI. The fix is structural: shorter‑lived credentials, strong 2FA, and OIDC‑based workflows that eliminate long‑lived publish secrets. (thehackernews.com)

What changed on November 5 (and what changes on November 19)

As of November 5, 2025:

• You can no longer create npm classic tokens via website, CLI, or API.
• New granular tokens with write permissions enforce 2FA by default; there’s a Bypass 2FA toggle for CI/CD.
• Existing write‑enabled granular tokens are capped at a 90‑day maximum lifetime; expirations after February 3, 2026 were adjusted to that date.

On November 19, 2025:

• All classic tokens are revoked.
• Long‑lived local publishing tokens are replaced with two‑hour session tokens for local publishes.

Important nuance: these changes apply to npm tokens used with the npm registry—not GitHub personal access tokens. (github.blog)

“npm token migration” in plain English

Migration means replacing any classic tokens with granular access tokens—or better yet, removing tokens from CI/CD altogether by using Trusted Publishing (OIDC). New write‑enabled granular tokens default to short lifetimes (with a max of 90 days), and 2FA is on by default. New TOTP setup has been disabled; passkeys/WebAuthn are the recommended path going forward. (github.blog)

Do I really need to rotate tokens every 7 days?

New write‑enabled tokens default to seven days (and can be configured up to a 90‑day maximum). You can avoid rotation pain in CI by switching to OIDC Trusted Publishing, which uses short‑lived identities instead of storing long‑lived registry secrets. (github.blog)

Will my GitHub Actions fail on Nov 19?

They will if your workflows still rely on classic tokens. Replace them with granular tokens (short‑lived and scoped) or adopt OIDC Trusted Publishing so no token is stored at all. (github.blog)

Why is npm doing this now?

The change follows a string of supply‑chain incidents, including the Shai‑Hulud worm (500+ packages impacted), which abused stolen tokens and CI permissions to spread. Short‑lived credentials and OIDC reduce that blast radius dramatically. (thehackernews.com)

Strategy first: choose your lane

You’ve got three viable lanes. Pick one per repository and stick to it.

1. Best: OIDC Trusted Publishing (no stored tokens)
   Use npm’s Trusted Publishing to publish from GitHub Actions or GitLab shared runners. The npm CLI handles the OIDC flow; you authorize a specific workflow file in npm settings. Requirements: npm CLI 11.5.1+, cloud‑hosted runners (no self‑hosted yet). (docs.npmjs.com)
2. Good: Granular tokens with short rotation
   Create write‑scoped granular tokens per package/scope; set reasonable lifetimes (e.g., 7–30 days), and automate rotation. Ensure Bypass 2FA is enabled if publishing in headless CI.
3. Interim: Local publishing with passkeys + 2‑hour sessions
   If you must publish locally, expect session tokens and strong 2FA. That’s safer than classic tokens but doesn’t remove human bottlenecks.

Quick win: Trusted Publishing in 20 minutes

Here’s a concrete, do‑once path for a GitHub Actions repo.

1. Upgrade tooling. Ensure Node 20+ and npm CLI >=11.5.1 in your workflow environment. (docs.npmjs.com)
2. Enable OIDC in your workflow. Add permissions: id-token: write and use actions/setup-node@v5 to set the registry auth. A minimal job:
   permissions:\n contents: read\n id-token: write\n\njobs:\n publish:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v5\n - uses: actions/setup-node@v5\n with:\n node-version: '22'\n registry-url: 'https://registry.npmjs.org'\n - run: npm ci\n - run: npm test\n - run: npm publish --provenance
3. Authorize the workflow in npm. In npmjs.com → your package → Trusted Publisher, select GitHub Actions, then set org/user, repo, and the exact workflow file name (case sensitive). (docs.npmjs.com)
4. Remove stored NPM_TOKEN. With OIDC, no long‑lived token should remain in repo or org secrets. Validate logs show OIDC authentication and provenance attached.
5. Prove it in staging. Publish a pre‑release tag (e.g., 1.2.3-rc.0) and verify npm provenance.

Want a deeper dive into CI/CD cutover patterns? We’ve published a focused CI/CD cutover guide for npm token migration with runner, permission, and rollback details.

Granular tokens done right (when OIDC isn’t an option)

Sometimes you’re on Jenkins, CircleCI, or a bespoke runner that can’t use OIDC today. If so, keep tokens tight.

• Scope narrowly. Grant only the write permissions your package needs; avoid account‑wide tokens.
• Rotate often. Treat seven days as a default; never exceed the 90‑day cap. Build rotation into CI via a secure job with human approval if required. (github.blog)
• Enable Bypass 2FA for CI tokens. Otherwise headless publishes will fail. Document the reason and owners. (github.blog)
• Quarantine storage. Store tokens only in your CI secret manager; block echoing, redact logs, and avoid shell interpolation that can leak.

Publishing from GitHub Actions but not ready for OIDC? Short‑term, you can continue using a granular token in secrets.NPM_TOKEN with an action like JS-DevTools/npm-publish; it also supports --provenance to attach attestations. Just remember: you’re accepting rotation and leakage risks until you switch to OIDC. (github.com)

Local publishing without drama

If you insist on publishing from your laptop for now, do it safely: move to passkeys/WebAuthn and expect two‑hour session tokens starting November 19. That change reduces the risk of a stolen all‑access token sitting on disk. (github.blog)

My practical guardrails:

• Use a dedicated, up‑to‑date machine profile with hardware‑backed passkeys.
• Run npm publish --provenance so consumers can verify how your package was built.
• Set calendar reminders to rotate any remaining tokens that still exist in tooling (e.g., for private dependency installs).

Why provenance matters now

Provenance and publish attestations let consumers verify that a package was built on a specific CI, from a specific repo, with a signed statement. npm verifies and signs an attestation when it accepts your publish. That helps stop unknown forks or “side‑door” builds from slipping into your supply chain. (github.com)

Data points leaders should know

Timelines and thresholds drive planning:

• November 5, 2025: Classic token creation disabled; write‑enabled granular tokens enforce 2FA; 90‑day max lifetime for existing write tokens, with expirations after February 3, 2026 shortened to that date. (github.blog)
• November 19, 2025: Classic tokens revoked; local long‑lived tokens replaced by two‑hour sessions. (github.blog)
• Security backdrop: Shai‑Hulud compromised 500+ packages and abused CI to replicate—credential sprawl and long‑lived tokens were the accelerant. (thehackernews.com)
• OIDC Trusted Publishing: GA for npm; supports GitHub Actions (hosted) and GitLab shared runners; requires npm CLI 11.5.1+. Self‑hosted runners are currently out. (github.blog)

10‑day cutover plan (use and adapt)

This is the play I run with teams to avoid surprises.

1. Inventory (Day 1): Grep for NPM_TOKEN across repos/CI; map who publishes what, from where, and how often.
2. Pick your lane (Day 1): Default to OIDC. Use granular tokens only where OIDC isn’t yet available.
3. Prove OIDC on one package (Day 2): Wire a single repo to Trusted Publishing, publish an -rc, verify provenance.
4. Org‑wide patterns (Day 3): Template a reusable workflow (composite action or reusable workflow). Document the permissions block and registry setup.
5. Secrets cleanup (Day 3–4): Remove classic tokens from org/repo secrets. Set up alerts for any job that references missing secrets.
6. Granular token rotation (Day 4): For non‑OIDC pipelines, mint scoped tokens, enable Bypass 2FA, set 7–30 day lifetimes, and schedule rotation jobs.
7. Developer experience (Day 5): For local publishers, enroll passkeys, run a dry‑run publish, and train on two‑hour sessions.
8. Block merges without provenance (Day 6): Add a CI check that fails if a release PR would publish without provenance/trusted publisher. (github.com)
9. Game day (Day 7–8): Cut over two to five high‑traffic packages; monitor install rates, error logs, and registry events.
10. Freeze window (Day 9–10): Hold on risky changes until after November 19; keep a rollback plan with npm dist-tag ready.

Edge cases and gotchas (read before you cut)

Self‑hosted runners. Trusted Publishing currently requires cloud‑hosted runners (GitHub Actions hosted or GitLab shared). If you’re self‑hosted, stick with granular tokens and harden the runner: no shared workspaces, ephemeral containers, locked‑down network egress. (docs.npmjs.com)

Private repos or packages. OIDC still works for publish, but provenance for private repos isn’t generated today. Don’t panic—your publish will work; you just won’t get the extra attestation. (docs.npmjs.com)

Monorepos with multiple packages. Authorize the workflow filename once per package on npm. If you publish from a called workflow via workflow_call, npm validates the calling filename—align these or you’ll see “Unable to authenticate.” (docs.npmjs.com)

Bypass 2FA for CI. It’s necessary for headless publish, but document the rationale, owners, and rotation cadence. And remember: it applies to granular tokens, not OIDC. (github.blog)

Security context: why this is non‑optional

Shai‑Hulud’s big lesson: CI is an amplifier. Once an attacker gets a token, they move at the speed of your pipelines—publishing trojanized versions, standing up covert Actions, and exfiltrating secrets. That’s why GitHub is nudging everyone off classic tokens, limiting token lifetimes, and steering teams to 2FA and OIDC. External coverage called the campaign one of npm’s largest compromises to date; if your estate still leans on static tokens, you’re betting against the trend. (tomshardware.com)

What to do next

• Adopt Trusted Publishing for every GitHub‑hosted publish path this week. It removes stored tokens and adds provenance. (docs.npmjs.com)
• For non‑OIDC systems, create granular tokens per package with minimal scopes, 7–30 day expiry, and automated rotation. (github.blog)
• Enroll passkeys for maintainers; expect two‑hour sessions for local publishing after Nov 19. (github.blog)
• Add a release gate that fails publishes without provenance and alerts when a job references a deleted secret. (github.com)

Where we can help

If you want a battle‑tested cutover plan tailored to your org, we’ve written a Nov 19 npm migration cutover plan and a practical last‑mile playbook to help you finish fast. If your pipeline also touches GitHub Actions limits or caching changes, see our brief on November 2025 Actions updates you should make now. And if you need a partner to ride shotgun through the change window, our engineering services team can step in.

FAQ: quick hits for decision‑makers

Can I postpone migration until after the holidays?

No. Classic tokens are revoked on November 19, 2025. Waiting risks broken releases and emergency fixes during your busiest period. (github.blog)

Will OIDC slow down our pipeline?

Not meaningfully. The OIDC exchange is fast and removes token management overhead while adding provenance. Most teams see less maintenance long‑term. (docs.npmjs.com)

What about non‑GitHub CI?

GitLab shared runners are supported for Trusted Publishing; for others, use granular tokens with tight scopes and rotations until support expands. (docs.npmjs.com)

Zooming out: this is a good moment to reduce secret sprawl, adopt passkeys, and make provenance your default. It’s the kind of invisible engineering that prevents the very visible incident.