Publish OpenAPI spec to npm via OIDC trusted publishing#19
Merged
gjtorikian merged 3 commits intomainfrom May 4, 2026
Merged
Conversation
The root package.json is private dev tooling; the npm publish workflow builds a fresh dist/package.json containing only the spec. Nothing under "dependencies" was actually consumed at runtime, so reclassifying them as devDependencies prevents misleading supply-chain tooling and clarifies that consumers should install the published @workos-inc/openapi-spec package instead of this repo.
SDK consumers and external integrators need a versioned, addressable artifact for the WorkOS spec rather than pulling from a moving git ref. OIDC trusted publishing keeps long-lived npm tokens out of the repo: GitHub Actions exchanges its OIDC identity for short-lived publish credentials, so the only secret to manage is the trusted-publisher config on npmjs.com. The workflow runs on spec changes to main (and on manual dispatch), bumps the minor version against whatever is on the registry, and emits both a git tag and a GitHub Release with the spec attached for non-npm consumers. README documents how to install and load the published package.
SDK consumers writing TypeScript want compile-time guarantees on request and response shapes; without published types they either copy-paste interfaces or pull the spec at build time themselves. Generating types as part of the publish workflow makes the same artifact serve both the YAML and the typed client use cases, in lockstep with the spec version. Uses openapi-typescript v7 (run via npx to avoid its TS ^5 peer-dep conflict with the repo's TS ^6) to emit a single types.d.ts with the standard paths/components/operations exports. The published package.json gains an exports map so TypeScript resolves "@workos-inc/openapi-spec" to the types while runtime resolution of "@workos-inc/openapi-spec/spec" still returns the YAML file path.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
release.ymlworkflow publishes@workos-inc/openapi-specon every spec change tomain(or manual dispatch), bumping the minor version against the registry and tagging a GitHub Release with the spec attached.id-token: write+--provenance) so noNPM_TOKENsecret lives in the repo — only the trusted-publisher config on npmjs.com.dist/package.jsonfor publishing; the rootpackage.jsonstaysprivate: trueas dev tooling, and its runtime deps are reclassified asdevDependenciesto reflect that.Bootstrap
The trusted publisher cannot be configured until the package exists on npm. One-time bootstrap:
version: 0.0.1(mirrors the workflow's Assemble step).npm publish --access publicwith a personal token /npm login.release.yml.0.1.0.Test plan
0.0.1to npm manually and configure the trusted publisher.release.ymlviaworkflow_dispatchand confirm it publishes0.1.0without a token.v0.1.0and the GitHub Release (withopen-api-spec.yamlattached) are created.open-api-spec.yaml,package.json,LICENSE.txt,README.md.mainand confirm the workflow auto-publishes0.2.0.