npm Token Migration: Your One‑Week Survival Guide

Clock’s ticking. The npm token migration is in its final stretch, and on November 19, 2025, npm will revoke all classic tokens and change how local publishing works. Earlier this month, GitHub and npm disabled creation of classic tokens and tightened lifetimes for granular tokens—moves that follow a string of supply‑chain attacks targeting maintainer credentials. If you release JavaScript packages, your pipelines and on‑call pages are in scope. (github.blog)

What changed—and when (with dates you can pin to a runbook)

Here’s the sequence that matters for planning and post‑mortems:

September 29, 2025: GitHub announces phased npm security changes: stricter authentication for publishing, classic tokens on the path out, and shorter lifetimes for granular tokens. Timeline targeted completion by mid‑November. (github.blog)

October 13, 2025: First wave lands. Newly created granular tokens with write permissions default to seven‑day expiry and have a 90‑day maximum. New TOTP 2FA setups are disabled (legacy TOTP keeps working, but you can’t add new devices), nudging maintainers toward hardware‑backed/WebAuthn 2FA. (github.com)

November 5, 2025: Classic token creation is disabled across the board. Write‑capable granular tokens enforce 2FA by default, and all existing write tokens are capped at a 90‑day maximum lifetime (anything beyond February 3, 2026 auto‑adjusted). GitHub previews the November 19 cutover: classic tokens get revoked; long‑lived local publishing tokens are replaced with short session credentials. (github.blog)

November 19, 2025 (cutover): npm permanently revokes classic tokens and switches remaining long‑lived local publishing flows to two‑hour session tokens. Expect noisy builds if you haven’t migrated. (github.blog)

Why the urgency? Because the threat model escalated

Two recent campaigns underline why npm is tightening the screws. In September and October, researchers tracked a self‑replicating worm (“Shai‑Hulud”) and related compromises that abused stolen maintainer tokens, implanted malicious install scripts, and even hid exfiltration inside CI logs. CISA urged developers to rotate credentials and audit dependencies. If your org relies on long‑lived tokens or permissive secrets, you were squarely in the blast radius. (cybernews.com)

Who’s at risk this week?

From what we’re seeing inside client estates, breakage clusters around:

• Monorepos with multiple packages and one shared NPM_TOKEN in organization secrets.
• Renovate/Release‑Please/semantic‑release flows that publish on tag push without OIDC.
• Self‑hosted runners or third‑party CI that haven’t been moved to Trusted Publishing.
• Private package installs in workflows (you still need a read‑scoped install token or a registry auth strategy even after you adopt OIDC for publishing). (docs.npmjs.com)
• Local release scripts (e.g., npm publish from laptops) that haven’t enrolled in WebAuthn‑based 2FA.

Good news: all of these have straightforward mitigations. Let’s get practical.

One‑week plan to ship the npm token migration without downtime

This plan assumes it’s the week of November 12. Adjust dates if you’re reading later.

Day 1: Inventory and blast radius

Make a quick catalog of where publishing happens. Search your org for NPM_TOKEN, npm publish, and setup-node usage; list repos, workflows, and package names. Flag any self‑hosted runners. While you’re there, enumerate secrets used for private installs versus publishing—those are different paths once you move to OIDC.

If you maintain public packages, pull download and dependency graphs to prioritize what must not break. Bonus: scan your lockfiles for suspicious install scripts and remote dependencies as a quick supply‑chain hygiene pass. (techradar.com)

Day 2: Flip your first package to Trusted Publishing (OIDC)

Trusted Publishing is now generally available for npm and works from GitHub Actions or GitLab shared runners. It replaces long‑lived tokens with short‑lived, workflow‑bound credentials and automatically adds provenance. Configure it once per package, then drop NPM_TOKEN from the publish step. (github.blog)

High‑level steps (GitHub Actions):

1. On npmjs.com, open your package settings → Trusted publishers → add a GitHub Actions publisher (org/user, repo, workflow filename, and environment). The workflow filename must match exactly. (docs.npmjs.com)
2. In your workflow, grant OIDC: permissions: id-token: write and run on a GitHub‑hosted runner. (docs.npmjs.com)
3. Publish with the npm CLI. With Trusted Publishing and recent npm, you can omit tokens; provenance is automatic. If you still publish manually, keep --provenance to emit attestations. (github.blog)

Yes, you can start with a low‑risk package to validate the pattern before rolling out to your core libraries.

Day 3: Roll out to the rest; keep private installs working

Migrate remaining packages by repeating the above. For workflows that install private dependencies, Trusted Publishing doesn’t change installs—you may still need a read‑only token or organization‑level registry auth for npm ci to succeed. Keep those read tokens scoped narrowly. (docs.npmjs.com)

If you’re publishing from tags, release‑please, or semantic‑release, the change is usually a two‑line diff: add id-token: write and remove the NPM_TOKEN secret from the publish step. Many publish actions already support OIDC natively with npm ≥11.5.1. (github.com)

Day 4: Lock down local publishing and 2FA

If your team still publishes from laptops, enforce FIDO/WebAuthn and rotate any long‑lived local tokens (which will shift to short session creds post‑cutover). Validate that maintainers can pass 2FA flows without friction. Document who’s allowed to publish locally and why. (github.blog)

Day 5: Kill stragglers

Delete remaining classic tokens from the npm UI. Replace any CI references to org secrets named NPM_TOKEN with OIDC‑first workflows—or, if you must keep tokens for now, regenerate as granular tokens with minimal scopes and near‑term expirations (remember: write tokens are capped at 90 days, with a seven‑day default for new ones since October 13). (github.com)

Day 6: Failure drills

Run a dry‑run publish on a non‑critical package and cut a real release on at least one high‑priority library. Watch logs for “Unable to authenticate” (often a filename or environment mismatch in the trusted publisher config) and for provenance errors when publishing from private source repositories (a known limitation). (docs.npmjs.com)

Day 7: Freeze window and comms

Assume churn on November 19. Freeze non‑essential changes to release workflows, post a status note for internal consumers, and confirm escalation paths if a pipeline fails. If you supply SDKs or client libraries to customers, send them a heads‑up that you’ve migrated and are publishing with provenance.

Quick reference: minimal OIDC publish workflow

Use this as a pattern, then adapt:

name: Publish to npm (OIDC)

on:
  push:
    tags:
      - 'v*.*.*'

permissions:
  contents: read
  id-token: write  # OIDC required

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: '22'
      - run: npm ci
      - run: npm test --if-present
      - run: npm publish
        # With Trusted Publishing and npm >= 11.5.1, no NPM_TOKEN is required
        # If you are not on Trusted Publishing, fall back to a granular token
        # uses: JS-DevTools/npm-publish@v4 with OIDC support

If you prefer a helper action and you’ve enabled Trusted Publishing, you can omit the token entirely; just be sure your Node setup includes an npm version that supports it. (github.com)

People also ask: Do I have to enable Trusted Publishing, or can I keep tokens?

You can limp along with granular tokens, but the incentives now push hard toward OIDC. New write tokens are short‑lived by design and tied to 2FA. Trusted Publishing eliminates long‑lived secrets, binds publishes to specific workflows, and emits provenance automatically—strong guardrails against the exact classes of compromises we saw this fall. (github.com)

Will my GitHub Actions break on November 19?

If any workflow still relies on classic tokens or assumes long‑lived local publishing tokens, yes—expect failures once revocation lands. Convert those jobs now, and where you truly can’t, regenerate as granular tokens with narrow scopes and short expirations and schedule rotation. (github.blog)

What about private packages and installs?

Trusted Publishing only changes publishing. Installing private packages in CI still needs authenticated access (for example, a read‑only token in .npmrc or an internal registry). Keep those read tokens scoped to install‑only and with tight expiries. (docs.npmjs.com)

A simple framework for teams: TOKENS, PUBLISH, INSTALL, PEOPLE

Use this four‑box to coordinate across engineering, security, and release management:

1) Tokens

Delete classic tokens. Replace any remaining write tokens with OIDC or, if unavoidable, granular tokens set to the minimum lifetime and scope. Confirm that new tokens created since October 13 comply with the seven‑day default and 90‑day max. (github.com)

2) Publish

Enable a trusted publisher on npm for every package you own. Update workflows with id-token: write and run on hosted runners. Cut a test release to validate provenance and workflow filename matching. (docs.npmjs.com)

3) Install

For private dependencies, retain a read‑only install token or switch to an internal registry. Double‑check that you aren’t leaking tokens via --debug logs or artifact uploads.

4) People

Move maintainers to WebAuthn 2FA and audit publisher roles. Disable ad‑hoc local publishes unless there’s a clear business case, and document when local session credentials are acceptable. (github.blog)

Data you can show leadership

Executives want impact and risk reduction. Share this snapshot:

• Cutover date: November 19, 2025—classic tokens revoked; long‑lived local tokens replaced by two‑hour sessions. (github.blog)
• Token policy: New write granular tokens default to seven days; all write tokens cap at 90 days. (github.com)
• Publishing security: Trusted Publishing GA for GitHub Actions and GitLab shared runners; adds automatic provenance, removing the need for --provenance. (github.blog)
• Threat evidence: NPM ecosystem saw hundreds of packages compromised; CISA advised credential rotation and dependency audits. (cybernews.com)

Related security changes you shouldn’t ignore

While you’re in the neighborhood, review your GitHub Actions threat model—especially around forks and pull_request_target workflows, which many teams have tightened this month. We’ve published a detailed breakdown of safer patterns and migration gotchas in our guide to GitHub Actions pull_request_target changes. If your pipelines run on macOS, also confirm your runner images aren’t pinned to deprecated versions; our quick fix for the macOS 13 runner deprecation still applies if you carry older workflows. For CI/CD cutovers under deadline pressure, grab our last‑mile Actions cutover guide as a template for planning and comms.

What to do next (developers)

• Migrate at least one high‑value package to Trusted Publishing today and release a patch to validate.
• Delete classic tokens; shorten lifetimes and scopes on any remaining granular tokens.
• Enable WebAuthn for all maintainers and remove unused TOTP devices from accounts. (github.com)
• Instrument alerts for failed publishes and provenance omissions.
• Audit lockfiles for suspicious scripts and remote URLs; rotate credentials if anything looks off. (techradar.com)

What to do next (business owners and product leads)

• Approve time for migration and drills this week; avoid scheduling feature releases on November 19.
• Ask for a single‑page rollout plan showing which repos moved to OIDC and who can still publish locally.
• Update vendor and customer communications if your SDKs depend on npm releases—set expectations for the cutover window.

FAQ: “We’re behind—what’s the fastest safe path?”

Start with your most‑installed package. Configure a trusted publisher on npm, add id-token: write in your workflow, and publish a patch. If private installs break, add a read‑only token just for npm ci. Then rinse and repeat across the rest of your packages. If you truly can’t adopt OIDC this week, regenerate granular tokens with minimum scopes and expirations—but set a date to retire them. (docs.npmjs.com)

Here’s the thing: the npm token migration isn’t just housekeeping. It’s a chance to pull long‑lived secrets out of your pipelines, ship provenance by default, and make the next “Shai‑Hulud”‑style attack much harder to pull off. If you want a partner to fast‑track the rollout, our team has been running these cutovers all quarter—reach out via our contact page and we’ll help you land it on time. For deeper step‑by‑step plans, check our focused guides on hardening GitHub Actions for npm migration and the full checklist of everything to fix by Nov 19.