If your publish step exploded last week, you’ve run into the npm token changes that landed mid‑November. Classic tokens are revoked, write tokens have tighter rules, and local publishing is moving to short‑lived credentials and stronger 2FA. Here’s a pragmatic path to get your releases unblocked today—and a durable migration so you don’t repeat this fire drill next quarter.
What changed on November 19—and why your pipeline broke
Two shifts collided. First, npm permanently revoked classic (legacy) tokens. Second, the platform tightened behavior around write‑scoped granular tokens—shorter lifetimes by default, stronger two‑factor expectations, and a push toward Trusted Publishing via OIDC. If your pipeline relied on a long‑lived token (often an NPM_TOKEN secret) created months or years ago, the publish job now returns authentication errors, usually E401 or E403.
There’s good intent here: fewer long‑lived secrets, more verifiable supply chains, and better defaults. But it’s real disruption if you ship every day.
Quick triage: unblock publishes in 30–60 minutes
If you have a release waiting, do this first. We’ll stabilize using a minimal‑scope granular token, then move to Trusted Publishing after the dust settles.
Step 1: Confirm the failure mode
Check the logs for any of the following: unable to authenticate, E401, requires two‑factor authentication, token expired. Also verify which runner image you use—some orgs also hit CI issues from older Node versions or image changes at the same time.
Step 2: Create a temporary granular token (least privilege)
Create a new granular token scoped to the exact package(s) you publish, with write access only where required, and an expiration no longer than 30–90 days. If your org mandates 2FA, you can enable the “bypass 2FA” flag specifically for this CI token—but only as a short bridge. Name it with an expiry hint, e.g., ci-publish-<package>-2026‑01‑15.
Step 3: Rotate CI secrets and use the token for one publish
Update your CI secret (commonly NPM_TOKEN). In GitHub Actions, verify your publish step uses NODE_AUTH_TOKEN (npm respects it automatically):
permissions: contents: readenv: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}run: npm publish --access public
Do a dry run first: npm publish --dry-run. If you’re using workspaces, publish via your releaser (Changesets, release‑please, semantic‑release) to avoid partial releases.
Step 4: Ship the queued release
Once production is unblocked, proceed to the durable fix below. Don’t keep this temporary token in place—treat it like a support bridge, not a new normal.
Durable fix: move to Trusted Publishing (OIDC)
Trusted Publishing establishes an OIDC trust between your CI provider and npm. Instead of planting a long‑lived token in CI, your workflow requests a short‑lived identity token at publish time. It’s tighter, auditable, and it enables automatic provenance on public packages.
How to switch in under an hour
Follow this order to avoid downtime:
1) Configure the trusted publisher in npm for the target package: provider (e.g., GitHub), repo, and the exact workflow filename that performs the publish.
2) In your workflow, grant id-token: write and contents: read permissions. Remove NPM_TOKEN from this job.
3) Keep your existing release automation (Changesets, release‑please, semantic‑release). The npm CLI will detect OIDC in the environment and exchange it for a short‑lived publish credential. You still run npm publish (or your tool’s equivalent).
4) Test on a pre‑release tag (e.g., 1.2.0‑rc.0) or a canary package before cutting a stable version.
5) Once verified, in the package’s npm settings, consider enabling the option that disallows token‑based publishing for that package. This locks publishing to OIDC and human 2FA flows.
Sample GitHub Actions snippet (Trusted Publishing)
name: releaseon: workflow_dispatch:jobs: publish: permissions: contents: read id-token: write runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version-file: .nvmrc cache: npm - run: npm ci - run: npm test --if-present - run: npm publish --provenance --access public
Notes: --provenance makes the intent explicit, though public packages published via Trusted Publishing get provenance automatically. For private packages, provenance won’t be attached; you can still use OIDC to eliminate static secrets.
People also ask: do I still need 2FA to publish?
Yes—for manual publishes from your laptop. CI publishes should rely on OIDC or tightly scoped, short‑lived tokens. If you temporarily set a granular token to bypass 2FA, sunset it once your OIDC workflow is proven.
People also ask: can I publish a brand‑new package with OIDC?
There’s a practical hiccup: enabling Trusted Publishing requires a package settings page, which exists only after the package exists. The safe pattern is to publish the very first version with a short‑lived granular token, immediately enable Trusted Publishing, then require OIDC for all subsequent versions.
People also ask: what about private dependencies or monorepos?
OIDC covers publishing. Installing private dependencies during builds still needs a read token (or your internal registry’s federated auth). In monorepos, wire OIDC to the release job while keeping read‑only tokens for npm ci. Consider release‑please or Changesets to coordinate multi‑package versioning and publication order.
Harden your posture: passkeys, scopes, allowlists, provenance
Here’s the thing: getting a green pipeline is the start, not the end. Use this moment to raise your floor.
• Move maintainers to passkeys/WebAuthn for account 2FA; phishing‑resistant MFA closes common gaps that TOTP can’t.
• Scope granular tokens to named packages and orgs; never use “all packages” unless absolutely required.
• Set short expirations (7–30 days) for any remaining write tokens; rotate on a calendar.
• Add CIDR allowlists for tokens used from fixed runners or networks.
• Publish with provenance so downstream consumers can verify where a package was built.
CI gotchas that bit teams this month
While chasing authentication errors, many teams also tripped on CI image and runtime changes:
• Node.js versions: older runners removing Node 18 forced upgrades. If you haven’t yet, standardize on Node 20, 22, or 25 in CI. Use actions/setup-node@v4 with node-version-file so dev machines and CI stay aligned. If you’re ready to move, our field notes on upgrading to Node.js 25 for faster JSON and safer defaults can help.
• ESM/CJS drift: switching Node majors can expose module‑resolution edges. Run tests on the exact Node version you publish with, and enable corepack to pin Yarn/pnpm versions.
• Caches: npm and Actions caches tied to Node version and lockfile can invalidate unexpectedly after runtime upgrades. Prime caches explicitly at the start of your release job.
A 7‑day migration plan you can hand to your team
Day 1: Unblock. Create a minimal‑scope granular token and ship the queued release. Log every token you created with owner and expiry.
Day 2: Prototype OIDC. Enable Trusted Publishing on one package, wire the release workflow with id-token: write, and publish a pre‑release.
Day 3: Roll out. Expand OIDC to your most active public packages; turn on provenance. Document the pattern.
Day 4: Reduce blast radius. Re‑scope or revoke any broad write tokens. Add CIDR allowlists where feasible. Shorten expirations.
Day 5: People and policy. Enforce passkeys for maintainers, require 2FA at the org and package level, and add a “break‑glass” procedure for emergency releases.
Day 6: Monorepo ergonomics. For workspaces, ensure your release tool orchestrates publish order and respects OIDC. Add a canary channel for early adopters.
Day 7: Lock in. For packages successfully publishing via OIDC, disable token publishing in settings. Add alerts on publish events and provenance changes.
Production checklist: don’t skip these
• Secrets inventory: list all npm‑related secrets across repos and environments. Remove stale items.
• Audit publish rights: every package should have named maintainers and a path for emergency revocation.
• Backups and rollbacks: automate npm dist‑tag rollbacks; protect latest with a release candidate gate.
• Automation parity: ensure your dry‑run, test, and publish steps run on the same Node version and same workflow image.
• Observability: emit a custom metric on publish success/failure; alert when a publish comes from an unexpected workflow or machine.
Leadership view: reduce release risk without slowing output
If you’re a CTO or product owner, the goal is simple: predictable releases with lower supply‑chain risk. Budget a single sprint to standardize your publishing path on OIDC, provenance, and passkeys; then measure outcomes—fewer credential incidents, fewer Friday‑afternoon publish outages. If you want a partner who has done this dance recently, our team can help you implement the guardrails without slowing delivery. See how we work on our services page or get in touch.
Related resources from our team
• If your pipeline failed the day the policies flipped, start with our earlier explainer: npm Token Changes: What Broke and How to Fix It.
• If your CI is still pinned to older Node versions, see AWS CDK Node.js 18 End of Support: Fix It This Week and our Node.js 25 upgrade playbook for migration patterns.
FAQ: npm token changes and daily operations
Will granular tokens keep working indefinitely?
They’ll keep working until their configured expiration. The spirit of the change is shorter lifetimes and tighter scope. Treat any write token as a “use sparingly, rotate often” tool. OIDC should be the default for automation.
Do I need to change my install steps?
No for public packages; yes for any private dependency fetched during CI. Keep a read‑only token for npm ci or use your internal registry’s auth integration.
Can I force all publishes through OIDC?
Yes—once you’ve proven the flow, disable token publishing at the package settings level. Keep a break‑glass process for human publishes that require 2FA.
What to do next
Developers:
• Rotate any lingering classic tokens you find in secret stores.
• Move your release job to OIDC this week; publish a pre‑release to confirm.
• Add provenance for public packages and set up alerts on publish events.
Engineering managers and founders:
• Make passkeys mandatory for maintainers.
• Standardize Node versions across dev and CI; avoid “works on my machine” on release day.
• Schedule a quarterly token audit and a monthly release‑path fire drill.
Zooming out, this is a healthy reset. Yes, it broke some pipelines. But it also nudges us toward a world where supply‑chain integrity and developer velocity aren’t at odds. Make the quick fix today, then invest a single sprint to land Trusted Publishing and provenance everywhere you can. Future‑you—and your customers—will be grateful.
