Add Typeship to an existing API repository

Connect your repository’s API spec to a Project, then choose where Typeship delivers each generated Target. The source and destination can share a repository.

Connect and generate

You need the Typeship CLI, an existing OpenAPI or GraphQL entrypoint, and access to the source and destination GitHub repositories. The example creates a CLI, MCP server, and TypeScript SDK; keep only the Targets and Deliveries you need. Replace the illustrative parcel/api repository and package names with your own.

# 1. check the existing credential; log in only if needed
typeship auth check --format json
# typeship login   # approve in the browser when no credential is configured

# 2. inspect existing Projects before creating one for this spec
typeship projects list --all
# For a matching Project, inspect its Spec and Targets and reuse it:
# typeship projects get <project_id>
# typeship specs get <spec_id>
# typeship targets list --project-id <project_id> --all

# 3. create a Project only if this Spec is not already linked
typeship projects create --name "Parcel API" \
  --spec '{"source":{"type":"repository","repository":{"provider":"github","identifier":"parcel/api","path":"openapi.yaml"}}}' \
  --targets '[
    {"name":"Parcel CLI","type":"cli","deliveries":[{"type":"repository","repository":{"provider":"github","identifier":"parcel/api","directory":"packages/cli","publish_on_merge":true}}]},
    {"name":"Parcel MCP","type":"mcp","deliveries":[{"type":"hosted_mcp"},{"type":"repository","repository":{"provider":"github","identifier":"parcel/api","directory":"packages/mcp","publish_on_merge":true}}]},
    {"name":"Parcel TypeScript SDK","type":"typescript_sdk","deliveries":[{"type":"repository","repository":{"provider":"github","identifier":"parcel/api","directory":"packages/sdk","package_name":"@parcel/sdk","publish_on_merge":true}}]}
  ]'

# 4. review the Generations started when the Project was saved
typeship generations list --project-id <project_id>

If the Spec is served at a URL rather than stored in GitHub, use --spec '{"source":{"type":"url","url":{"url":"https://..."}}}'; Typeship checks it every 30 minutes when automatic regeneration is on.

Configure delivery and updates

Install the GitHub App. Repository sources and destinations use the Typeship GitHub App. If a repository is not connected, the Console prompts you and projects create returns an installation link. Install it once per GitHub account or organization.

Choose the destination. A Delivery selects a repository and directory. Use the API repository for a shared pull-request stream, or a dedicated repository for an independent package release history. See Add a package to your repo.

Publish from the repository. publish_on_merge adds a reviewed root workflow plus one manifest per Target. Registry credentials stay with GitHub; configure trusted publishing before merging the first release. See Publish your packages and Publish from a monorepo.

Make custom package code explicit. Commit helpers, exports, tests, and dependency changes to the Target's Draft. Typeship carries them into later Drafts and merges them with newly generated files. It stops on ambiguous ownership or overlapping edits and reruns checks against the resulting package. Use config and Spec patches for behavior that should be generated consistently. See Customize generated packages.

Review the first generated update. Automatic generation starts enabled for new Projects. Confirm the package builds and its Delivery points to the intended repository and directory. See Keep a package current.

Review each changed Target independently. A Spec change opens one destination pull request per changed Target. Source pull requests receive Preview Generations before the Spec merges. See Generation behavior.

What can go wrong