Regeneration

ProAvailable on Pro and EnterpriseThe free plan includes one hosted generation.

A generated package is a snapshot of one spec. Regeneration keeps it current. Link a project to its spec once, and every change becomes a pull request in your normal review flow. Nothing lands unseen.

The loop

1. The spec changes.
2. typeship notices, fetches the spec, applies the project's spec patches, and generates every language.
3. One pull request opens per language in that language's destination repository, with the API changes listed in the body and CHANGELOG.md updated in the destination.
4. You review and merge.

How changes are detected

Repository sources. A push to the default branch that touches the spec path triggers regeneration immediately.

URL sources. typeship polls the URL every 30 minutes and regenerates when the content changes. The poll also acts as a backstop for repository sources in case a webhook is missed.

Both are governed by one switch, auto-regen, off by default so the first generation is always one you asked for. Turn it on in project settings (or --auto-regen true) once the output is what you want; off, only generate now and the API regenerate.

Change detection compares the spec's hash against the last generation. An unchanged spec is skipped. Generate now in the console always runs, so you can force a rebuild after changing settings.

The pull request

Each pull request is opened from a branch named typeship/regen-<language>-<generation id> against the destination's default branch. The title is Regenerate acme (TypeScript, 42 operations). The body carries:

• The language, package name, operation count, line count, and destination directory.
• The first generation warnings, if any.
• API changes: what was added, removed, or changed since the last generation, with breaking changes marked.
• A note that files removed from the generated package are not deleted by the revision. Delete stale files in your review if a resource disappeared.

The first generation of a project has no changes to report, so its pull request has no changelog section.

The changelog

Every regeneration pull request reports what it does to that repository's API surface, measured against the surface that is actually merged there. The result is written to the pull request body and prepended to CHANGELOG.md in the destination directory:

## 2.4.0 (2026-08-18) (1 breaking)

### Added
- `accounts.close()`: POST /accounts/{id}/close

### Removed (breaking)
- `accounts.archive()`: POST /accounts/{id}/archive

### Changed
- `accounts.list()`: GET /accounts
  - **breaking** param: status is now required

The changelog comes from the real surface diff, not from commit messages, so it is accurate even when the spec was edited by hand.

The baseline is the destination. Each pull request commits .typeship/surface.json next to the package: the API surface and version that shipped. The next regeneration reads that file from the destination's default branch and diffs against it. A regeneration pull request that was closed without merging therefore never becomes the next one's point of comparison; what the body says will change is what merging it changes. A destination that has no manifest yet is measured against the previous generation, and the pull request says so and adds the file.

Breaking changes

A regeneration pull request carries two signals beyond the changelog:

• A commit status named typeship/semver. It fails when the diff has breaking changes and the package version does not bump the major (the minor, before 1.0). It passes otherwise, with the counts in its description. The first tracked regeneration of a destination has no previous version to compare with, so it passes with a note.
• A breaking label whenever the diff removes a method or field, changes a type, or makes an input required. The label is added when the GitHub App can label pull requests in that repository, and skipped quietly when it cannot.

The status is advisory by default. Make it a required check in the destination's branch protection and a regeneration that breaks the SDK without a version bump cannot merge until info.version in the spec moves. Leaving it advisory is the right default for most teams: by the time the pull request opens the API has already changed, and an SDK that cannot catch up to it helps nobody.

Which repository gets which signal:

A project with a URL source gets the destination signals and nothing before merge. When breaking changes land in such a project, the pull request body and the console say so and link to the settings page where the spec's repository can be linked.

Destinations

Each language's pull request goes to that language's destination. See Destinations. If a pull request cannot be opened (no repository configured for that language, or the GitHub App is not installed on it), the generation still succeeds and is recorded in the console. The package is still downloadable there.

Manual regeneration

Any project can be regenerated on demand:

• Generate now on the project page runs the full loop, including pull requests.
• POST /v1/projects/{id}/generations through the typeship API regenerates a URL-sourced project and returns the files, without opening pull requests. Use it when you want to drive the packages into your own pipeline.

Where custom code belongs

The generated package is wholly owned by the generator. Regeneration replaces it, and anything you wrote inside it is destroyed. Wrap the client in a module you own instead. See Extend the client.

Versioning

The generated package version follows the spec's info.version. When that value is not semver (for example v2 or a date), the version is 0.1.0. Bump info.version in the spec to release, and the next pull request carries the new version. If you publish to a registry, that version is what ships. See Publish your packages.

The typeship/semver status holds the version to the diff: a breaking change needs a new major, and the pull request names the version to set when it does not have one.