Sourced*

Engineering

Publish a generated TypeScript SDK with npm trusted publishing

· 2 min read · Sourced

  • npm
  • typescript
  • sdk
  • trusted-publishing
  • provenance

npm trusted publishing is the better way to publish generated SDKs because it avoids long-lived npm tokens. Instead of storing a token in CI, npm trusts a specific GitHub Actions workflow through OIDC and attaches provenance to the package.

For generated SDKs, the workflow should be:

  1. Generate the TypeScript SDK from OpenAPI.
  2. Build and smoke-test it.
  3. Run npm pack --dry-run.
  4. Show the file list and compatibility report.
  5. Wait for approval.
  6. Publish through a trusted GitHub Actions workflow.

The publish step should be intentional. Previewing an SDK should never publish it.

What npm trusted publishing needs

At a minimum:

  • an npm package name you own or can create
  • a GitHub repository connected to the package
  • a GitHub Actions workflow path npm trusts
  • id-token: write permission in that workflow
  • package metadata with correct repository
  • an npm publish step using provenance

A simplified workflow looks like this:

name: Publish SDK
on:
  workflow_dispatch:
    inputs:
      version:
        required: true
        type: string

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: https://registry.npmjs.org
      - run: npm ci
      - run: npm run build
      - run: npm publish --provenance --access public

With trusted publishing configured, npm verifies that this exact workflow in this exact repository is allowed to publish.

Why generated SDKs need an approval gate

A generated SDK can be technically valid and still wrong for customers:

  • method names changed because operationId changed
  • request types became stricter
  • README examples use a test base URL
  • package exports are missing CJS compatibility
  • a generated file list includes fixtures
  • semver did not bump correctly

Sourced's npm readiness flow is designed to stop before publish, show these checks, and ask for explicit approval only when the package should go live.

What Sourced should do vs what npm should do

Sourced should:

  • generate the SDK preview
  • run build and smoke checks
  • compare the SDK surface against the previous version
  • verify package metadata
  • prepare a publish request
  • tell you exactly what trusted publishing setup is missing

npm should:

  • own package identity
  • verify trusted publisher configuration
  • attach provenance
  • record the package version

That boundary matters. Sourced should not ask for a broad npm token when trusted publishing can solve the release path more safely.

What to search for when debugging

Common npm trusted publishing failures:

  • "This package has no trusted publisher configured"
  • "GitHub Actions OIDC token missing"
  • "repository field does not match"
  • "npm publish provenance failed"
  • "package already exists with this version"

If you see one, fix setup before rerunning publish. Do not fall back to a broad token unless you have a short-term incident reason.

Read the npm publishing guide or see Sourced client packages.