Skip to main content

​
What is OIDC trusted publishing?

OIDC trusted publishing lets CircleCI publish packages to npm without storing npm auth tokens. Instead, CircleCI provides a short-lived OIDC token ($CIRCLE_OIDC_TOKEN_V2) that npm validates against a trusted publisher configuration on each package. If the token’s claims match (organization, project, pipeline, context), npm accepts the publish.
Trusted publishing vs. provenance attestation — these are different things. Trusted publishing is an authentication mechanism (how CI proves it’s allowed to publish). Provenance attestation is a supply-chain security feature (cryptographically linking a package to its source). npm’s --provenance flag only works on GitHub Actions and GitLab CI — it is not supported on CircleCI. This project uses OIDC for authentication only.

​
When to configure

After adding a new @agent-facets/cli-* platform target. Each new package needs its own trusted publisher entry on npm before CI can publish it.

​
Setup steps

1

Seed the package on npm

npm login # one-time, uses your personal npm account
bun seed # publishes v0.0.1 placeholders, prints package URLs
The seed script will print out a list of packages that need to be configured.
2

Configure trusted publishing on npm for each package that was listed

1
Open the package’s npm settings page (URLs are printed by bun seed)
2
Under Publishing access, add a new trusted publisher
3
Enter the CircleCI OIDC values:
FieldValue
Organization IDd6dfd694-6b06-4d51-a5bd-a15b3efe977b
Project IDc7b3dd0a-e9b0-4e95-8345-fc984443e02b
Pipeline Definition IDd404b478-dd19-4c68-891f-4cf97396b1a7
Context IDs84962527-275c-495e-83c3-31c79cf1e181
VCS Origingithub.com/agent-facets/facets
3

Verify

Re-run bun seed to confirm all packages exist on npm. The script reports “All packages already exist on npm” if seeding was successful.
The main package (agent-facets) and existing platform packages already have OIDC configured.

​
Where to find these values

ValueLocation
Organization IDCircleCI org settings
Project IDCircleCI project settings
Pipeline Definition IDCircleCI project pipeline settings
Context IDsCircleCI context settings (release context)
VCS OriginGitHub repository URL (without https://)

​
Platform packages

The 12 platform packages that need OIDC configuration: 
@agent-facets/cli-darwin-arm64
@agent-facets/cli-darwin-x64
@agent-facets/cli-darwin-x64-baseline
@agent-facets/cli-linux-arm64
@agent-facets/cli-linux-arm64-musl
@agent-facets/cli-linux-x64
@agent-facets/cli-linux-x64-baseline
@agent-facets/cli-linux-x64-baseline-musl
@agent-facets/cli-linux-x64-musl
@agent-facets/cli-windows-arm64
@agent-facets/cli-windows-x64
@agent-facets/cli-windows-x64-baseline

​
How it works

  1. The release CircleCI workflow runs in the release context, which makes $CIRCLE_OIDC_TOKEN_V2 available.
  2. The release script calls scripts/lib/ci-io.ts:mintOidcToken() to fetch a fresh OIDC token.
  3. The token is set as NPM_ID_TOKEN in the environment.
  4. When npm publish runs, npm sends the token to the registry. The registry validates the token’s claims against the package’s trusted publisher configuration.
  5. If the claims match, the publish succeeds. No long-lived npm tokens are involved.