npm's January 2027 Publishing Change: Move CI to OIDC or Staged Releases

npm plans to remove direct publishing with granular access tokens in January 2027. Compare OIDC and stage-only releases, plus a migration checklist.

Developer Tools & Security•~7 min read•November 9, 2026•By QZ-L Editorial
#npm#GitHub Actions#CI/CD#software supply chain
Looking for related guides? Start with the qz-l Learning Center and explore more tutorials in this topic cluster.

If a release workflow publishes an npm package with a granular access token that bypasses two-factor authentication, put a migration on the calendar now. npm's current access-token documentation says direct publishing of new package versions with granular access tokens will be removed in January 2027.

That is not a notice that every npm token disappears. Read-only tokens and stage-only tokens have different uses, and npm's token change is specifically about publishing new versions directly. The practical choice for maintainers is whether CI should publish without a long-lived write token using OpenID Connect (OIDC), or submit a staged version that a person reviews and approves before it goes live.

Which release path fits?

Path CI credential How a version goes live Best fit
OIDC direct publish Short-lived identity token from the CI provider; no npm publish token The workflow runs npm publish Releases where a trusted automated workflow is allowed to publish immediately
OIDC staged publish OIDC identity token, configured to allow staging but not direct publishing CI runs npm stage publish; a maintainer reviews and approves with 2FA Automated builds that should not be able to make a version public on their own
Stage-only granular token A scoped npm token stored as a CI secret CI stages the version; a maintainer approves with 2FA Providers or setups that cannot use npm trusted publishing yet

For a GitHub Actions workflow, OIDC staged publishing is a strong default when your release process can include an approval step. It removes the long-lived publish token from CI while preserving a human decision before publication. If a team intentionally allows automatic releases, OIDC can also be configured for direct publishing. The stage-only token is a fallback when OIDC is not available, not a way to avoid reviewing the npm token's scope and lifecycle.

What is actually changing?

npm removed legacy access tokens in November 2025. The remaining granular access tokens can be restricted by package, scope, permission, and expiration. npm's documentation now says that direct publishing with a granular access token will end in January 2027. Stage-only tokens are a separate option: they can submit a version for review, but cannot publish a new version directly.

Stage-only does not mean read-only. npm documents other write operations that remain available to a stage-only token, including deprecating versions and moving distribution tags. Treat one as a write credential, limit its package access, store it as a CI secret, and revoke it when it is no longer needed.

Set up OIDC staged publishing in GitHub Actions

The pieces have to agree: the npm package's trusted-publisher settings identify the GitHub repository and workflow, and the workflow must be allowed to request an OIDC token. The job still needs the ordinary checks that make a release trustworthy—tests, build steps, and controls on who can create release tags.

In the package's Settings → Trusted Publisher area on npmjs.com, select GitHub Actions and enter the organization or user, repository, and workflow filename. Use the filename (for example, publish.yml), not its path. If the workflow uses a GitHub environment, configure the same environment in the trusted-publisher settings. These values are identity checks, so capitalization and spelling matter.

For GitHub publishing, npm also requires the package's repository.url in package.json to match the GitHub repository. Check that field before diagnosing an OIDC failure as a permissions problem.

Here is an illustrative workflow for a package that stages each version tag for approval:

name: Publish package

on:
  push:
    tags:
      - "v*"

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: "24"
          registry-url: "https://registry.npmjs.org"
          package-manager-cache: false

      - run: npm ci
      - run: npm test
      - run: npm run build --if-present
      - run: npm stage publish

This is a template, not a tested release pipeline. Before relying on it, check the npm CLI version in the runner: trusted publishing requires npm CLI 11.5.1 or later, and staged publishing raises that minimum to 11.15.0. Both require Node 22.14.0 or later. Keep the release job on a supported hosted runner; npm currently lists GitHub-hosted runners, GitLab.com shared runners, and CircleCI cloud, but not self-hosted runners.

The id-token: write permission lets this job ask GitHub for an OIDC token. It does not by itself authorize an npm publish. npm must also recognize the configured repository and workflow, and the trusted-publisher configuration must permit the command being run. For this staged workflow, allow npm stage publish and leave direct npm publish disabled. Avoid giving unrelated jobs the OIDC permission.

After npm stages a version, a maintainer can inspect it in the CLI or npmjs.com and approve it with 2FA. The approval is the point at which the staged package becomes available on the registry. A team that has chosen immediate publication can instead allow direct publishing for its trusted publisher and use npm publish; that trades the extra human checkpoint for automation.

Keep dependency access separate from release access

Trusted publishing authenticates the publish operation. It does not authenticate npm install or npm ci. If a package needs private dependencies, use a separate read-only granular token for installing them. Do not keep a broad publish token in the workflow just because dependency installation also needs credentials.

If you are using a stage-only token instead of OIDC, grant it access only to the package or packages the workflow releases, and do not enable direct-publish access. The human approval step still uses 2FA. This reduces the impact of a compromised workflow, but the token can still perform other permitted write operations, so it remains sensitive.

A migration checklist

  1. Find every publish credential. Check repository and organization secrets, release workflows, reusable workflows, and package .npmrc files. Identify which credentials publish and which, if any, only read private dependencies.
  2. Choose the release policy. Decide whether a trusted workflow may publish directly or whether every version needs a maintainer approval. Prefer OIDC where supported; use a stage-only token if the provider cannot establish the required trust.
  3. Match the npm trust configuration. Confirm the repository, workflow filename, and optional environment. npm says a new trusted-publisher configuration must complete its first successful publish within two days or it expires; schedule the initial verification accordingly.
  4. Update and verify the toolchain. Use Node 22.14.0 or later and npm CLI 11.15.0 or later for staged publishing. Verify the exact CLI version used by CI rather than assuming it matches a developer's local installation.
  5. Test the intended path before removing credentials. Confirm that the release job can authenticate and stage or publish as designed. For a staged path, verify that a maintainer can review and approve the result with 2FA. Do not test by publishing an unintended version to a public package.
  6. Remove obsolete write access. Once the replacement works, revoke old direct-publish tokens and restrict token-based publishing for the package. Keep only the intended stage-only token if you chose that fallback, plus any separately scoped read-only credentials that private dependency installation still requires.

For GitHub Actions specifically, also make sure release tags cannot be created casually and review changes to the publishing workflow with the same care as changes to package code. A correctly configured OIDC identity cannot compensate for a release workflow that an untrusted change can alter.

Provenance is useful evidence, not a safety verdict

npm says trusted publishing through GitHub Actions or GitLab automatically creates provenance for public packages built from public repositories. Provenance can help a consumer check where and how a package was built; it does not prove that the source code is benign. npm currently documents that provenance is not generated for CircleCI trusted publishes, and private source repositories are not eligible for this automatic provenance path.

The main migration goal is not to add a badge. It is to make the publishing authority match the release policy: remove long-lived direct-publish credentials from automation, constrain the workflow identity, and add an explicit approval step when a person should decide whether a staged version goes live.

References

Related Posts

GitHub Actions Is Blocking pull_request_target by Default: What to Change Before December

Prepare public GitHub repositories for the December 2 pull_request_target protection with safer workflow patterns and a focused migration checklist.

GitHub Actions Workflow Logs: Detect and Respond to Leaked Secrets

Enable GitHub workflow log secret scanning carefully, review preview gaps, and revoke leaked credentials with a practical response checklist.

Kijiji Scam Alert: A Fake Payment Email with a Fraud Link

A real phishing attempt after posting a Kijiji ad, how the fake page looked convincing, and a practical checklist to avoid scam links.