Multiple trusted publishing configurations, and better visibility for staged packages

[leobalter]

We shipped three updates to npm publishing this week. The headline is that a package can now have more than one trusted publishing configuration — but the staged publishing improvements matter just as much if you've been publishing since we turned on malware scanning.

---

Why the one-configuration limit was a problem

Trusted publishing lets a GitHub Actions workflow publish to npm using a short-lived OIDC token instead of a long-lived access token. No secret to leak, no token to rotate, and every publish carries a verifiable origin.

That worked well if you published from exactly one workflow. A fair amount of projects don't.

A typical repository has a release.yml for stable versions, a prerelease.yml for betas, maybe a separate workflow for release candidates or a staging environment. Under the old model, only one of those could use trusted publishing. For everything else, maintainers had two options for extended automation, and neither was good: collapse everything into one workflow; keep a long-lived token - the bypass2fa GAT - for the remaining paths.

Using the bypass2fa GAT is the outcome we most wanted to avoid — an easily portable publish credential sitting in CI, valid for days to months, with no human present when it's used.

Either way, the one-configuration limit meant that adopting trusted publishing was often partial. You'd secure your main release path and leave the rest on tokens.

What changed

A package can now hold multiple trusted publishing configurations. Each one is a complete, standalone entry with its own criteria, including an opt-in permission for direct publishing.

You add, list, and remove them from your package's settings page on npmjs.com. All new configurations have default access for staged publishing (using the npm stage publish command).

How they interact

The model for multiple configurations is deliberately simple, and worth understanding before you set things up:

Configurations are additive. Each one grants a publish path. None of them can restrict, narrow, or override another. There's no deny rule and no precedence — adding a configuration can only ever expand what's allowed, never reduce it.

Any single match authorizes. When a publish or stage request comes in, we check the OIDC token against the package's configurations. If it satisfies any one of them, the action is authorized. The others don't need to match.

Order is not guaranteed. Because matching is binary and one match is enough, the order in which we evaluate configurations doesn't change the outcome. We don't sort them, and we don't promise a stable order. Please don't build tooling or logic that assumes a particular configuration "wins" — that's the one assumption that could break on you.

There's a limit of 10 configurations per package. In practice that comfortably covers stable, prerelease, release candidate, and staging flows with room to spare. If you're hitting it, we'd genuinely like to hear about your setup.

Staging is on by default; direct publishing is opt-in

This is the part we'd most encourage you to think about.

Every configuration can stage a package out of the box. Publishing directly to the registry is a separate permission you have to turn on per configuration.

We recommend leaving direct publishing off and keeping your configurations staging-only.

The reason is straightforward. Staged publishing puts a human approval step between your workflow and the registry. If a workflow is compromised — a malicious dependency in your build, a bad action, a pull request that shouldn't have run — the worst case is a staged version sitting in a queue waiting for someone to look at it. Without staging, that same compromise pushes a version straight to everyone who installs your package.

Short-lived credentials remove the risk of a stolen token. Staging removes the risk of a workflow that runs exactly as designed, but was made to do the wrong thing. They solve different problems, and they're strongest together.

Staged publishing is a much stronger and recommended mechanism as it allows packages to have proof of presence when published. We are exploring ways you can also add proof of presence during your workflows and validate this within the OIDC claim used for publishing a package. We consider the use of a 2FA challenge as proof of presence. Staged Publishing requires an npm 2FA challenge to promote your packages to the registry whenever you approve them from your staging queue.

Staged publishing now waits for the scan

In late July we introduced publish-time malware scanning: packages are scanned before they become available for install, which adds a short delay between publishing and availability.

That created an awkward moment in the staged queue. You could hit approve on a package that hadn't finished scanning yet, with nothing on screen explaining why the result wasn't what you expected.

Now the approval button stays disabled while a scan is in progress and enables once the scan completes. The page refreshes the status every minute, so you can leave it open and watch it clear on its own.

Scanning usually takes around a few minutes minutes, though it can run longer at peak times or for larger packages.

Version history in the versions tab

Maintainers now see a detailed history on the versions tab of their package, showing whether each version was approved, rejected, or is still staged.

Previously, if a version didn't show up where you expected, working out what happened meant piecing it together from notifications and memory. Now it's on the page — one place to check when a release doesn't land the way you planned.

We intend to expand this view so you can have one place to review all your account and organizational publish activity views, per package and/or condensed. More to come soon!

Getting started

If you're already using trusted publishing, nothing changes for your existing configuration. Add a second one for whichever publish path is still on a token, and check whether direct publishing is enabled where staging would do.

If you haven't set it up yet, the trusted publishers documentation is the place to start. The multi-configuration model means you no longer have to reshape your workflows to fit the feature.

Tell us what you think

A few things we'd especially like to hear:

• How many configurations do you end up with, and what are they for?
• Is 10 enough?
• Are you keeping configurations staging-only, or is something pushing you toward direct publishing?
• Anything still forcing you to keep a long-lived publish token around?

That last one is the question behind all of this work. Every remaining answer is a gap we want to close.

[danez]

Nice, now just please add BitBucket Cloud pipelines as trusted publisher. 💜

[leobalter]

I want to add more providers, and it's in our roadmap: https://github.com/orgs/community/discussions/208130

[SerenModz21]

Anything still forcing you to keep a long-lived publish token around?

Managing dist-tags still requires a long-lived token. There has been an open issue about it for over a year now: npm/cli#8547

In addition, @favware/npm-deprecate helps to automate deprecating versions from development-based tags (e.g., @next, @dev, @rc, etc.). It can also remove dist-tags, which is useful when removing PR tags upon merging. However, long-lived tokens are still required.

Discord.js and Sapphire also use the npm-deprecate package.

[ckohen]

This has changed recently with the changes to 2FA bypass GAT, I'm going to be raising this in that thread as well, but we can now no longer remove PR publish dist-tags via CI. It is strictly impossible without 2FA as it cannot be done with the bypass token and also cannot be done with trusted publishing.

This is absolutely ridiculous and this isn't the only completely blocked action either. It really seems like npm just doesn't want to support open source work at all at this point.

[leobalter]

we are soon including opt-in support for dist-tag in trusted publishing configs.

I have in my radar fine grained access to GAT and other extended permissions for trusted publishing configs. Thanks for the feedback @SerenModz21!

[sudocurse]

Anything still forcing you to keep a long-lived publish token around

We're still looking for an OIDC-scoped mechanism for org/team membership for publishing

(FYI, didn't see this update mentioned in the other thread #201329 - might want to drop a link there)

[leobalter]

yes, we have work in our backlog for namespace wide configurations. Please take a look here: https://github.com/orgs/community/discussions/208130