Beyond One OIDC Workflow: Governing npm Trusted Publishing at Scale

A package team adds a second trusted-publisher configuration for a hotfix workflow. The new rule is narrower: a specific repository, a protected environment, and a workflow intended only for signed emergency tags. The team assumes the new rule has effectively tightened publishing. It has not. The older broad configuration is still valid, and npm authorizes a stage or direct publish when an incoming OpenID Connect (OIDC) identity matches any configured publisher. The rules are additive, and matching order is not a policy control.

That distinction turns multiple npm trusted publishers from a convenience feature into a release-governance problem. A forgotten workflow, a renamed file, a stale direct-publish option, a token kept for recovery, or a self-hosted runner path can preserve more authority than the team intended. Provenance can show where a package came from, but it cannot prove that the authorizing workflow was appropriately scoped, reviewed, dependency-hardened, or free from compromise.

The operational goal is therefore not merely npm tokenless publishing. It is a release-trust topology in which every legitimate release path is explicit, every configuration is treated as an additive authorization rule, high-impact packages use staged approval where practical, provenance is verified rather than admired, and negative tests prove that unauthorized repositories, workflows, environments, forks, refs, and runner types cannot publish. The playbook below builds that topology package by package, then covers token retirement, configuration drift, monitoring, incident response, rollback, and a 45-day rollout with production sign-off evidence.

What Changed in npm Trusted Publishing on September 3, 2026

npm trusted publishing itself was not new in September 2026. GitHub announced general availability of npm trusted publishing with OIDC on July 31, 2025, replacing long-lived publish credentials in supported CI paths with short-lived identity tokens. The September 3, 2026 release expanded the authorization model and changed how staged releases are governed.

The GitHub Changelog release on September 3, 2026 described three generally available changes. First, a package can have multiple trusted-publisher configurations instead of one. Second, staged versions cannot be approved until npm's publish-time malware scanning has completed. Third, maintainers can review staged, approved, and rejected version history in the package versions interface. Current npm trusted-publisher documentation allows up to ten configurations per package.

The same documentation sets an important compatibility boundary: trusted publishing requires npm CLI 11.5.1 or later and Node.js 22.14.0 or later. Staged publishing has a higher npm CLI minimum, 11.15.0, with Node.js 22.14.0 or later. Supported trusted-publishing paths are GitHub Actions on GitHub-hosted runners, GitLab CI/CD on GitLab.com shared runners, and CircleCI cloud. Self-hosted runners are not supported for this trust flow. Those boundaries belong in release policy, not in a setup footnote.

Define the Release Trust Boundary Before Adding Configurations

Start from the package as a production release surface. The trust boundary includes the npm package and maintainers, source repositories, CI workflow definitions, protected environments, release refs, runner class, registry settings, approval rights, provenance expectations, and any recovery credential. The package owner is accountable for what may be published. The platform team owns reusable release infrastructure. Security owns control design and exception review. Operations owns monitoring and incident execution. Executive risk acceptance is reserved for deliberate exceptions that leave material bypass paths.

Inventory Packages, Maintainers, Repositories, and Workflows

Do not begin by clicking Add trusted publisher. Build a release registry first. For a monorepo, one repository may map to dozens of packages with different maintainers and different blast radii. For a multi-repository estate, one package may be released from a primary repository, a backport repository, and an emergency workflow. Inventory both directions: package to workflow and workflow to package.

The release registry should be the control plane for adoption and later audits. It can live in a governed database, configuration repository, or service catalog, but it must be queryable and versioned. Broader supply-chain evidence, such as dependency inventory and compliance records, belongs beside this release view rather than inside it; Refonte Learning's article on SBOM compliance platforms for the Cyber Resilience Act is useful context for that separate inventory layer.

Classify Stable, Prerelease, Hotfix, and Recovery Paths

Release classes need explicit policy because they represent different urgency and impact. A stable release of a widely consumed library should not automatically inherit the same authorization path as a canary build. A hotfix path may need lower latency, but that does not justify a permanent broad publisher or a long-lived token that remains usable after the incident.

Practitioner rule: if a path exists only because 'we might need it someday,' keep it disabled rather than continuously authorized. Recovery is a capability to activate under control, not a standing bypass. Document who can activate it, what evidence is required, the maximum activation window, and the exact steps to return the package to its normal trust state.

Understand Additive Matching and Why Configuration Order Cannot Protect You

Multiple npm trusted publishers behave like an OR expression, not a firewall rule list. If configuration A matches a broad release workflow and permits direct publish, configuration B can be narrower and stage-only without reducing A's authority. npm documents that configurations are independent and additive, that one match is sufficient, and that evaluation order is not guaranteed. There is no deny rule, no first-match precedence, and no 'most specific wins' behavior.

The acceptance test is therefore about the union of permissions. For every package, enumerate every configuration and every traditional publishing method. Then ask: what is the most permissive path that remains valid? That answer, not the newest configuration, describes the real production boundary.

• Remove obsolete broad configurations after a successful replacement has soaked and negative tests have passed.

• Never keep a permissive configuration as a silent fallback. If fallback is required, name it as a recovery control with an expiry.

• Review direct-publish permission independently for every configuration.

• Treat package maintainer changes and workflow renames as authorization changes that require re-verification.

Stop condition: if the team cannot explain why each existing publisher is still required, do not add another one. Freeze configuration growth, map the current authorization graph, and remove or quarantine stale paths first.

Design a Trusted-Publisher Matrix for Monorepos and Multi-Repository Estates

The hard cases are not single-package repositories. In a monorepo, a shared release workflow may technically be able to publish many packages even when ownership is distributed. In a multi-repository estate, a single package may be released from separate stable, maintenance, or migration repositories. The matrix must capture package-to-workflow relationships explicitly instead of trusting repository membership as a proxy for release authority.

Shared workflow libraries can improve consistency, but they also create transitive trust. A package-specific workflow that calls a reusable workflow still needs the correct caller identity, permissions, trigger controls, and environment protections. Broad platform pipelines should stay focused on orchestration; the separate Refonte Learning discussion of DevOps platform engineering and agentic pipelines is relevant to that platform layer, while this playbook keeps the authorization decision package-specific.

Separate Repository, Workflow, and Environment Claims

Each claim proves something different. The repository identifies the source project. The workflow criterion identifies the authorized release definition. The optional environment links the release to a CI deployment boundary that can impose reviewers, branch or tag restrictions, and other protection rules. None of those claims replaces the others.

For GitHub Actions, npm configuration uses the workflow filename, and the file must exist in the repository's .github/workflows directory. The matching fields are case-sensitive. For GitLab, the top-level CI file path is part of the trusted-publisher configuration. CircleCI uses organization, project, pipeline definition, version-control origin, and optional context identifiers rather than a GitHub-style workflow filename. Current npm trusted-publisher documentation should be rechecked before changing these fields because provider claim models can evolve.

Drift frequently appears as a case change, workflow rename, repository transfer, environment rename, or reusable-workflow restructuring. Because existing trusted-publisher connections cannot simply be edited in place, treat a change as delete-and-create with a controlled overlap window. During that overlap, both configurations may authorize release, so direct publishing should remain disabled unless the package risk model explicitly requires it.

Choose Stage-Only or Direct Publishing by Release Risk

Staging changes the consequence of workflow compromise. A stage-only publisher can submit a candidate tarball, but it cannot make that version live without a maintainer approval step. Direct publishing removes that human boundary. GitHub's September 3 release note recommends keeping configurations stage-only where practical, and new configurations created after that release default to staging capability with direct publish as an opt-in.

A practical policy is to make stable and emergency production paths stage-only by default, then require an exception record for direct publish. The record should name the package, configuration, release class, threat model, compensating controls, owner, review date, and rollback plan. Do not approve direct publishing because OIDC is 'secure.' OIDC addresses credential lifetime and identity binding; it does not neutralize malicious workflow changes, compromised actions, dependency substitution, or an overpowered repository maintainer.

Stop condition: if the workflow can be modified by people who are not authorized to release the package, direct publishing is inappropriate. Fix code ownership, branch protections, workflow permissions, and environment controls before enabling direct publish.

Build the Staged Approval and Malware-Scanning Gate

npm staged publishing documentation defines a distinct state before registry availability. Automation can submit a package with npm stage publish without an interactive two-factor authentication (2FA) prompt. A maintainer later reviews and approves the staged version with 2FA, consistent with npm's package publishing 2FA requirements. Since the September 3, 2026 update, approval remains unavailable until npm's publish-time malware scan has completed.

Malware scanning is a gate, not a safety guarantee. The July 28, 2026 npm publish-time malware-scanning announcement describes automated analysis before availability, and npm's Threats and Mitigations documentation provides broader registry-security context. Neither proves absence of malicious code, vulnerable dependencies, credential harvesting logic, or a compromised build chain. Pair the registry gate with dependency and artifact controls appropriate to your ecosystem. Refonte Learning's overview of Trivy and modern DevOps security tooling belongs around that broader scanning layer, not as a substitute for release authorization.

Define the Human Approval and 2FA Ceremony

Approval should be a release decision, not a button click. The approver needs enough context to determine that the staged bytes are the intended output of the intended workflow. Separate duties where risk warrants it: the person who changes the release workflow should not be the sole approver of the first production release using that change.

1. Confirm the package name, version, dist-tag, release class, and linked change set.

2. Confirm the expected repository, commit, workflow identity, runner class, and protected environment.

3. Review the packed artifact or a deterministic file manifest for unexpected files, generated secrets, or build output drift.

4. Confirm test, dependency, policy, and malware-scan gates are complete. A completed malware scan is necessary but not sufficient.

5. Verify release notes and any breaking-change declaration against the staged version.

6. Approve with the maintainer account and required 2FA. Do not share approval accounts or bypass proof of presence.

7. Capture approval evidence and confirm the live version and provenance after publication.

Define an approval timeout. A staged candidate that sits unreviewed beyond the package's risk window should be rejected and restaged from a fresh commit rather than approved from stale context. For an emergency release, shorten review logistics, not the trust model: name the incident commander, use a predeclared reviewer pool, and record why the emergency path was invoked.

Generate and Verify Provenance for Every Published Version

Provenance answers a traceability question: where and how was this package built? Current npm provenance documentation states that trusted publishing automatically generates provenance for qualifying public packages from public repositories when publishing through supported GitHub Actions or GitLab CI/CD paths. CircleCI trusted publishing does not currently provide npm provenance attestations. Provenance also has its own baseline requirements and should be checked against current npm documentation before changing release images.

Provenance is not a vulnerability scan and not a judgment about workflow quality. The same workflow can reliably attest to a malicious or poorly reviewed build. Consumer-side verification should therefore combine provenance with version policy, dependency review, integrity checks, and the consumer's own risk controls. The operational value is that provenance narrows forensic questions: which repository, commit, and build identity produced the version under investigation?

Treat missing provenance as a control event when policy says it should exist. Do not allow a release pipeline to switch providers, repositories, or visibility in a way that silently removes attestation while preserving publish authority.

Secure GitHub Actions, GitLab, and CircleCI Release Workflows

Provider support is deliberately bounded. npm currently supports GitHub Actions on GitHub-hosted runners, GitLab.com shared runners, and CircleCI cloud for trusted publishing. A self-hosted runner, a different CI product, or a private runner fleet is an unsupported path for npm OIDC publishing and needs a controlled alternative rather than a fake equivalence.

For GitHub, GitHub's OIDC security documentation explains that workflow identity is conveyed through signed claims. Hardening must extend beyond OIDC issuance. Pin third-party actions to immutable commits where appropriate, review reusable workflows, prevent untrusted pull-request code from reaching release jobs, protect release tags, and require environments for high-impact publication. GitHub's secure-use guidance for Actions is the right companion reference for workflow hardening.

For GitLab, validate the ID token audience expected by npm and use protected environments and protected refs so the CI platform enforces who can initiate the release. For CircleCI, validate the organization, project, pipeline definition, VCS origin, and context restrictions against the npm package configuration. CircleCI's npm OIDC publishing guidance and GitLab's ID-token documentation should be treated as provider-specific implementation references, while npm remains the authority for what its registry accepts.

Runtime hardening remains separate from publishing identity. If release jobs also build containers or deploy into Kubernetes, apply the relevant runtime controls there; Refonte Learning's Kubernetes production hardening article covers that distinct boundary without changing which workflow is authorized to publish an npm package.

Minimize OIDC and Workflow Permissions

OIDC should be issued only to the release job that needs it. In GitHub Actions, id-token: write permits the job to request an OIDC token; it is not a general registry write permission, but granting it to unrelated jobs expands the number of places from which trusted identities can be requested. Pair it with the minimum repository permissions needed for checkout and attestation. Do not use write-all as a shortcut.

permissions:
  contents: read
  id-token: write
  attestations: write   # only if the workflow explicitly needs GitHub artifact attestations
  packages: read        # only if build inputs require it

A release trigger is part of authorization even when npm does not directly evaluate every trigger detail. Require stable releases from protected tags or a controlled manual dispatch that resolves to a reviewed commit. Fork-originated pull requests must never inherit a path to a publish-capable job. Reusable workflows should accept only the inputs needed for release and should not allow arbitrary command injection through package names, tags, or script parameters.

Migrate Away From Long-Lived npm Tokens Without Losing Recovery

Trusted publishing removes a long-lived npm publish token from supported release jobs, but it does not eliminate identity or secrets from the release system. Private dependency installation may still require read credentials. Registry administrators and maintainers still authenticate. CI providers have account recovery and environment controls. Unsupported runners may require a traditional publishing method. Recovery itself needs credentials or privileged identities.

The token-retirement sequence should be reversible without leaving a permanent bypass. First, deploy OIDC for a low-risk release and prove both the expected publish and the relevant negative cases. Second, revoke the old publish token, not merely remove it from the CI secret store. Third, execute a controlled failed attempt with the old credential or a safe equivalent validation to prove the registry no longer accepts it. Fourth, retain a separate break-glass procedure that requires human activation and automatically expires.

This is where the security benefit becomes concrete. Long-lived CI/CD secrets can leak through logs, build artifacts, compromised automation, or developer tooling. Refonte Learning's analysis of AI coding agents leaking CI/CD secrets illustrates the broader exposure problem; npm OIDC publishing reduces one class of standing credential, while least privilege and secret governance remain necessary for everything around it. GitHub's September 29, 2025 npm authentication and token-management changes also provide historical context for the registry's move toward stronger authentication controls.

Rollback condition: if OIDC publishing fails for a supported path after cutover, do not immediately recreate a broad permanent token. Use the documented break-glass route with a narrow package scope and explicit expiry, then fix the trust configuration and remove the temporary credential.

Test Negative Paths, Compromised Workflows, and Configuration Drift

A successful release proves only that one authorized path works. It does not prove that unauthorized paths fail. Production sign-off requires negative authorization testing, controlled attempts designed to match everything except one expected claim. The evidence should show npm rejection, the CI identity used, the attempted package/version, and reviewer confirmation that no version became available.

Perform these tests in a safe package or version namespace that cannot confuse consumers. Do not intentionally publish malicious code or attempt to bypass registry safeguards. Negative testing is authorization testing, not exploit testing.

Prove Unauthorized Workflows Cannot Publish

The most revealing case is the stale publisher. Suppose the hardened configuration uses a protected environment and stage-only permission, but the old configuration still matches the same repository and workflow without the environment and permits direct publishing. The expected first test may succeed because the old rule is still valid. That is not a test failure; it is evidence that the authorization union is broader than intended. Remove the stale configuration, repeat the test, and preserve both results as proof of remediation.

Configuration drift testing should run after workflow renames, repository transfers, CI-provider migrations, maintainer changes, or environment-policy changes. Automate inventory comparison where APIs and tooling permit, but keep a human review for the question automation cannot answer: does this publisher still represent an approved business release path?

Roll Out Configuration Changes Across a Package Portfolio

Use risk rings rather than editing every package at once. Start with internal or low-impact packages whose consumers and release cadence make failures easy to observe. Then move to public prerelease paths, normal public packages, critical libraries, and finally emergency or recovery paths. A ring advances only after happy-path publishing, negative tests, provenance checks where supported, and token-retirement evidence pass.

Worked example: consider a hypothetical @acme/payments-sdk package in a monorepo. Discovery finds two release paths: release-payments.yml for stable tags and an old release.yml configuration that once published several packages directly. The team adds a new stage-only publisher tied to the payments workflow and a protected npm-production environment. The first negative test deliberately omits the environment. Unexpectedly, direct publication remains authorized through the old configuration. Because matching is additive, the new rule did not constrain the old one.

The team stops the rollout, removes the obsolete broad publisher, and retests. The no-environment path now fails. A staged candidate from the correct workflow succeeds, waits for malware scanning, receives a two-factor approval, and publishes with verifiable provenance from the expected repository and commit. The legacy publish token is then revoked, and a controlled test confirms it no longer works. During a later hotfix drill, the normal stage-only path is used with an emergency reviewer rota rather than a standing direct-publish bypass. Final evidence links the package registry, workflow commit, failed negative tests, approval event, provenance, token revocation, and rollback procedure.

Stop conditions for any ring include an unauthorized path that can publish, provenance missing where policy requires it, OIDC silently falling back to a token, package maintainers not knowing who may approve, or monitoring gaps that prevent attribution. Roll back by restoring the last known-good publisher set, not by retaining both old and new rules indefinitely.

Monitor Releases, Staged History, and Publisher Configuration Changes

Release monitoring should join registry evidence with CI evidence. npm version history shows staged, approved, rejected, and published states. CI audit logs show who changed workflows, environments, contexts, secrets, or runner settings. Provenance identifies the source and build path for supported releases. Package download anomalies can indicate rapid propagation of a bad release, while maintainer changes can alter who is able to configure or approve publishing.

Recommended service-level objective (SLO): a production package version should be attributable to its source repository, release commit, CI workflow, approving maintainer when staged, and publisher configuration within one investigation query. If responders need to reconstruct that chain manually across multiple systems during an incident, the release process is not sufficiently observable.

Configuration monitoring matters as much as release monitoring. A change from stage-only to direct publish, a new second publisher, or a deleted environment criterion changes the trust boundary even if no package is released immediately. Treat those settings as security-sensitive production configuration, with review and alerting comparable to CI environment or protected-branch changes.

Respond to a Compromised Publisher or Incorrect Release

Incident response must separate containment of future publication from handling of the version that is already staged or live. Removing a compromised trusted publisher can stop that OIDC path, but it does not undo a published version. Revoking a token does not remove a malicious workflow. Rejecting a staged version does not remediate the repository compromise that created it.

For a compromised workflow, remove or disable every publisher that can match it, not just the configuration you think was used. Because matching is additive and unordered, incident responders should work from the full publisher inventory. Preserve the configuration state before destructive changes where doing so does not delay containment. Registry history, CI logs, provenance, and workflow commits may be needed to distinguish an incorrect release from an identity compromise.

For an incorrect but non-malicious release, the immediate technical action may be a corrected version and deprecation of the bad one, depending on npm policy and consumer impact. Do not overwrite history or fabricate provenance. Communicate exact affected versions and remediation guidance. If a staged version is wrong, reject it before approval, correct the source, and stage a new version rather than treating approval as an editable checkpoint.

Recovery is complete only when the compromised authorization route is gone, emergency credentials are revoked or disabled, the intended publisher set is re-established, negative tests fail as expected, and the next legitimate release is traceable end to end. An incident closed after 'we rotated a token' is incomplete if a permissive OIDC workflow remains authorized.

Establish the Evidence Required for Production Sign-Off

Production sign-off should be package-level. A platform can offer secure defaults, but each package has its own maintainers, repository mappings, release cadence, recovery requirements, and consumer blast radius. The evidence package should let an independent reviewer answer four questions: who may publish, under what CI identity, through which human and automated gates, and how will the organization prove that unauthorized paths fail?

A practical package acceptance checklist is short enough to use but strict enough to reject a weak migration:

• Every legitimate stable, prerelease, backport, and emergency workflow is mapped to an approved publisher or an explicitly controlled alternative.

• Every configured publisher has a current owner and business purpose, and obsolete broad configurations are removed.

• Stage-only versus direct publishing is documented per configuration and matches package criticality and rollback risk.

• Controlled negative tests prove unauthorized repositories, workflows, environments, forks, refs, renamed workflows, unsupported runners, stale publishers, and removed configurations cannot publish through the intended trust path.

• Provenance is present and verified wherever npm supports it and package policy requires it; documented unsupported cases are visible, not silently ignored.

• Long-lived publish tokens are revoked for normal supported CI paths, residual credentials are least-privilege, and the recovery route is time-bounded.

• Monitoring can attribute each production release to source, workflow, configuration, and approver, and configuration drift creates a reviewable event.

• Incident response and rollback have been rehearsed, including publisher removal, staged rejection, credential revocation, corrected release, and recovery verification.

• Engineering, platform, security, operations, and risk-acceptance owners are named.

This evidence model is intentionally narrower than a general DevSecOps governance program. For broader policy structures, compliance and governance in DevSecOps provides adjacent context; the package release standard here remains centered on npm authorization, stage/publish decisions, and recoverable trust.

The acceptance standard is simple to state and demanding to prove: every legitimate workflow can release through its approved path, every unauthorized workflow fails under controlled testing, stage-only and direct-release choices reflect package risk, provenance is verifiable where supported, recovery is time-bounded, and obsolete tokens and publisher configurations are removed. Teams that can produce that evidence have moved beyond 'tokenless' toward actual npm supply chain security.

For practitioners building the underlying skills, Refonte Learning's Cybersecurity & DevSecOps Program describes a three-month program at roughly 12 to 14 hours per week covering secure CI/CD pipelines, application-security testing, infrastructure security and automation, OWASP and threat modeling, incident response, risk mitigation, network and cloud security, and security-workflow automation. Those foundations are directly relevant to release governance, but the program page does not claim npm trusted-publishing, staged npm approval, or registry-specific incident response as named curriculum.

Treat every npm package as a production endpoint. Treat every trusted-publisher configuration as another authorization rule. Add flexibility only when you can also prove the resulting union of permissions, observe it, and remove it safely. That is the point at which multiple npm trusted publishers become an auditable release platform rather than an accumulation of convenient workflows.