Generate in CI

A Project watches its Spec and opens destination pull requests with automatic generation on by default. Use CI when your pipeline needs to trigger that workflow, generate a package into its own checkout, or validate a live API response.

The Typeship CLI generates packages and operates Projects. A generated CLI calls your API. Install the Typeship executable on your runner before running the steps below.

Trigger the project's normal pull request

The Typeship CLI reads its key from TYPESHIP_TOKEN and prints JSON, so it drops into any job. Create a key under api keys in the console and store it as a secret.

name: Regenerate SDK
on:
  workflow_dispatch:
  schedule:
    - cron: "0 6 * * 1"

jobs:
  regenerate:
    runs-on: self-hosted
    env:
      TYPESHIP_TOKEN: ${{ secrets.TYPESHIP_TOKEN }}
    steps:
      - name: Regenerate and open destination PRs
        run: typeship projects generate prj_your_project_id

projects generate runs the same URL- or repository-sourced pipeline as a Spec change. It records one Generation per Target and the immutable Spec Revision, then opens one pull request per changed destination with the release-style compatibility report and semver check. If the package already matches a destination and no Draft is open, no new commit, branch, or pull request is needed. An existing Draft stays open. Do not unpack and recommit it: that would bypass the Delivery workflow you configured.

Generate ad hoc, no project

packages generate runs the generator on any spec without a Project or signing in. Supply a Spec and one Target descriptor:

typeship packages generate \
  --spec '{"url":"https://typeship.dev/examples/petstore/openapi.yaml"}' \
  --target '{"type":"typescript_sdk"}' \
  --out packages/typescript

Or with curl:

curl -s https://typeship.dev/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"spec":{"url":"https://typeship.dev/examples/petstore/openapi.yaml"},"target":{"type":"python_sdk"}}'

Anonymous and Free ad hoc generation covers 25 operations of a spec without retaining spec contents or generated files. An anonymous URL run without source headers may return a seven-day claim link; it does not consume the Free Project slot unless someone claims it. Use it when this checkout's CI owns the commit; use a project when Typeship should maintain history, source watching, compatibility reporting, and destination pull requests.

Fail the build on spec drift

Generate a separate CLI Target, build it, then run a read-only operation with --validate. Use the generated CLI executable for the check.

This workflow uses the same public, unauthenticated Petstore API as the Quickstart:

name: Validate API response
on:
  workflow_dispatch:

jobs:
  validate:
    runs-on: self-hosted
    steps:
      - uses: actions/setup-go@v5
        with:
          go-version: "1.23"
      - name: Generate the CLI
        run: >-
          typeship packages generate
          --spec '{"url":"https://typeship.dev/examples/petstore/openapi.yaml"}'
          --target '{"type":"cli"}'
          --out packages/petstore-cli
      - name: Build the CLI
        working-directory: packages/petstore-cli
        run: |
          go build -o petstore .
      - name: Validate the live response
        run: packages/petstore-cli/petstore pets list --json --validate

The job succeeds when the sample API returns Mochi with the documented id and name fields. For your API, replace the Spec URL, discover a read-only command with --help, and supply the credentials named in its generated README through CI secrets.

--validate checks the emitted schema subset for the request and response being exercised. It does not cover uncalled operations or prove complete compatibility. A schema mismatch returns a validation error and fails the command; investigate the reported field in Fix a spec that will not generate.