npm Token Migration: Your Final‑Week CI/CD Plan

Clock check: it’s the week of November 11, 2025. On November 5, npm tightened the rules; on November 19, remaining classic tokens are revoked. If your release jobs still depend on those legacy secrets, you’re staring at 401s on publish and a blocked roadmap. This guide lays out a concrete, last‑mile plan to finish the npm token migration in seven focused workdays—without lighting up incident channels.

What changed—and what breaks on November 19

Three facts to anchor your plan:

First, you can no longer create classic npm tokens. Existing classic tokens still work only until November 19, 2025, when they’re permanently revoked. Any pipeline that injects a classic token for npm publish or npm dist-tag will fail the next time it runs after the cutoff.

Second, granular access tokens with write permissions now default to 2FA enforcement and have a hard maximum lifetime—90 days—so long‑lived write tokens are out. There’s a “Bypass 2FA” switch specifically for CI/CD, but it’s off by default and should be used sparingly and narrowly scoped.

Third, local/manual publishing is shifting to short‑lived sessions. That’s a win for account safety, but it removes the crutch of ever‑green tokens on laptops or shared build boxes. The durable fix is Trusted Publishing with OIDC: your CI provider exchanges a signed identity token for a short‑lived npm credential at publish time. No secret to rotate, nothing to leak.

One operational note: ensure your environments use an npm CLI recent enough to support trusted publishing. If you haven’t touched your build images in a while, patch now—don’t discover the version gap during your release window.

npm token migration: a pragmatic seven‑day plan

You don’t need a six‑month program; you need a clean decision tree and disciplined execution. Here’s the plan I’ve used with platform teams this week.

Day 1 — Inventory the blast radius

Make the invisible visible. Enumerate every place you publish or mutate registry state:

• Release pipelines and monorepo publish steps (npm publish, changesets, lerna, or custom scripts)
• Tagging and dist‑tag automation (npm dist-tag, promotion jobs)
• Manual release playbooks used by maintainers
• Container images and runner AMIs baking tokens as environment variables
• Third‑party Actions and shared templates that reference legacy secrets

For each flow, capture: CI provider, runner type (cloud vs self‑hosted), package visibility (public/private), and whether the job needs write access or just read (most only need read). This informs the path you pick next.

Day 2 — Choose the right path per package

Make a simple rule and stick to it:

• Public packages from repos on cloud runners: Use Trusted Publishing (OIDC). It’s safer and simpler than babysitting tokens and automatically attaches provenance for public packages.
• Private packages or self‑hosted runners without OIDC: Use a granular token with the narrowest scope and lifetime, and enable “Bypass 2FA” only when the job truly needs write.
• Manual local publishes (rare): Plan for short‑lived sessions and strong 2FA. Treat laptops as liabilities; minimize this path.

Write this down as a decision memo so teams stop debating in Slack. If you want a deeper pre‑read on risk and sequencing, see our Nov 19 cutover playbook.

Day 3 — Convert GitHub Actions to Trusted Publishing

Most orgs run on Actions, so you’ll get the fastest risk reduction here. High‑level steps:

1. Remove stored npm publish tokens from repo/org secrets for repos moving to OIDC. Less to leak, nothing to rotate.
2. Configure trusted publishing in npm for the package, authorizing your repo/workflow. Do this once per package.
3. Update workflow YAML to let the npm CLI detect OIDC and publish without a token env var.
4. Dry‑run a release in a non‑prod tag or a canary branch.

Here’s a minimal GitHub Actions example that works cleanly with OIDC‑based publish:

name: release
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 ci
      - run: npm test --if-present
      - name: Publish via OIDC
        run: npm publish --provenance --access public

Notes from the field:

• permissions: id-token: write is non‑negotiable for OIDC.
• --provenance adds supply‑chain attestations for public packages.
• Don’t set NPM_TOKEN at all in this job—let the CLI exchange the OIDC token under the hood.

If your repos are heavy on reusable workflows, good news: GitHub recently raised the ceilings to 10 nested reusable workflows and 50 calls per run. That makes it easier to centralize this pattern without hitting limits across a monorepo or platform library. We broke down that change here: GitHub Actions: November changes that matter.

Day 4 — Tackle monorepos and tags

Multi‑package repos add two wrinkles: selective publishes and dist‑tag promotions. Your goals:

• Ensure the workflow runs in a context authorized as a trusted publisher for each package it might publish.
• Keep provenance intact by publishing from the workflows that built the artifacts; avoid “sidecar” publish steps that move built tarballs between jobs with different identities.
• Replace any npm dist-tag manipulations using classic tokens with an OIDC‑capable job or, if unavoidable, a granular token scoped to a single package org and the dist‑tag permission only.

For large orgs, a central reusable workflow that accepts the package path and access level as inputs removes most of the per‑repo thrash. Given the higher nesting limits, this structure now composes cleanly.

Day 5 — GitLab CI and Jenkins patterns

On GitLab, use the built‑in OIDC integration for jobs that run on GitLab‑managed runners. For self‑managed runners without OIDC, issue a granular token with minimal scope and the shortest workable lifetime, and store it in a masked variable. Rotate on a schedule, and gate the job behind a protected environment. On Jenkins, prefer agents that support OIDC; if that’s not in the cards this week, isolate the credential using a credentials store plugin, scope it to the publish job, and audit job logs to ensure the token never prints.

One principle holds across providers: don’t stamp secrets into base images. Bake only tools; inject credentials at runtime via the runner’s identity or a vault that issues short‑lived tokens. If you discover tokens inside container layers, treat the image as compromised and rebuild from scratch.

Day 6 — Validate, observe, revoke

Do a full‑dress rehearsal:

• Create a pre‑release tag (for example, v1.2.3-rc.0) and run your pipeline end‑to‑end.
• Check the npm package page for provenance on public packages and confirm the publisher and CI workflow match expectations.
• Audit logs in your CI provider for any use of deprecated secrets.
• Revoke classic tokens that the rehearsal proves you no longer need. Don’t leave them lingering “just in case.”

Then add alerts: set up monitors for 401/403 against the registry, and surface publish failures to a human‑on‑duty channel. For the next two weeks, you want noisy detection over silent failures.

Day 7 — Freeze, cutover, rollback

Declare a short freeze window around November 19 UTC. Communicate two things clearly: who’s on the hook for hotfix publishes, and what “rollback” means. In OIDC land, rollback rarely means reverting code; it usually means re‑authorizing the right repo/workflow as a trusted publisher or flipping a granular token scope. Write that down in your runbook where sleepy humans can find it.

People also ask

Do I need GitHub Actions to use Trusted Publishing?

No. Trusted publishing depends on OpenID Connect support from your CI provider, not Actions specifically. GitHub Actions is well supported today. Some providers require cloud‑hosted runners; self‑hosted runner support may be limited. Also, make sure your npm CLI is modern enough to detect OIDC automatically.

Should I enable “Bypass 2FA” for CI tokens?

Only if you must. If OIDC is an option, use it. When you do enable Bypass 2FA, keep token scope narrow, store it in the provider’s secrets manager with masking, set the shortest expiration you can live with, and monitor usage. Treat it as a bridge, not the destination.

What happens to monorepo publish tooling like Changesets?

It works fine with OIDC, provided the publish step executes in the same workflow that built the packages and that the workflow is authorized as a trusted publisher for each package. The most common footgun is building in one job and publishing in another job that lacks OIDC permissions or authorization; keep them together or propagate the identity properly.

Do private org packages or internal registries change the calculus?

Yes. Many teams route installs through internal proxies or private registries. Publishing often still targets npm, but read traffic is split. Validate that your proxy configuration doesn’t clobber OIDC behavior at publish time. For private packages published to npm, authorize the same workflow as a trusted publisher and use --access restricted if needed.

Risks and edge cases you should plan for

Self‑hosted runners without OIDC. If your security model or network requires self‑hosted runners and OIDC isn’t supported, you’ll need granular tokens for now. Keep them short‑lived, rotate, and isolate runners per repo to limit blast radius.

Container images with baked tokens. This is the silent killer. Search your Dockerfiles for ENV NPM_TOKEN and base images for secrets. If found, rebuild images and rotate any exposed token immediately; assume it leaked long ago.

Third‑party Actions and templates. Shared CI templates or third‑party Actions may inject NPM_TOKEN behind your back. Read their docs and pin versions that are OIDC‑aware. If a third‑party Action hasn’t been updated, replace it or fork it.

Manual publishes from laptops. If you must keep them, require passkeys for 2FA, restrict who can publish, and use short‑lived sessions. Don’t allow long‑lived tokens on endpoints.

Compliance attestation. Some customers now ask for provenance on public packages. With OIDC and --provenance, you get attestations that integrate with standard SBOM/SCM pipelines. Capture a screenshot and stash it with your release notes.

Verification checklist (save this)

• All repos that publish to npm have permissions: id-token: write in the release workflow and no NPM_TOKEN secret in use.
• Each package lists the correct trusted publisher (repo/workflow) and a human approver confirmed it in the npm UI.
• Monorepos publish from the same job that built artifacts; no cross‑job tarball shuffling.
• Dist‑tag jobs either use OIDC or a token scoped only to tagging for a single package org.
• No base images, AMIs, or self‑hosted runners bake in tokens.
• Alerts fire on registry 401/403 and publish step failures; on‑call knows the playbook.

What to do next

Leads and owners, here’s your one‑pager:

• Schedule a short freeze window and staff a release captain for November 18–20 UTC.
• Run the rehearsal publish today and tomorrow; revoke any no‑longer‑needed classic tokens.
• Update your developer docs with the new release flow and screenshots of the npm trusted publisher config.
• Audit third‑party Actions and templates; fork or replace anything that still relies on NPM_TOKEN.
• Plan a follow‑up sprint to migrate remaining self‑hosted jobs to OIDC or reduce token lifetime to days, not months.

Helpful resources on our site

If you want deeper dives and templates, start with what will actually break on Nov 19, then pull from the Nov 19 cutover playbook. If your publishing flows live in Actions, our November GitHub Actions changes cover the new nesting limits and macOS runners that can speed up iOS/macOS pipelines you’re updating anyway. And if you want hands‑on help putting this in place, see our engineering services.

Zooming out: why this is worth the hassle

Yes, this week is busy. But the direction is the right one. The industry has seen too many supply‑chain incidents triggered by leaked or weak credentials. Short‑lived, identity‑bound tokens and provenance‑aware builds shift risk away from human memory and toward verifiable automation. The teams that lean in now will spend less time firefighting later—and ship faster because they’ve removed a class of brittle secrets from their systems.

If you’re already done, take a victory lap and move on to the next obvious win: standardizing your release workflows as reusable building blocks across repos. With Actions’ higher composition limits, that refactor just got simpler—and you’ll never again hunt for a stray token hiding in a forked YAML file.