Generation behavior

Regeneration produces updated Targets from your Project's current Spec and configuration. With automatic generation enabled, Typeship detects source changes and prepares a pull request for each changed Target with a repository Delivery.

FreeAvailable on every planOne Project retains and diagnoses the complete Spec; every selected Target regenerates 25 operations without a run quota.

To set up the workflow, follow Keep a package current. For a worked example with preserved custom code, conflicts, and a breaking client change, follow Review an API update. This page explains change detection, review, and file ownership.

What happens during regeneration

1. The Spec changes, including a referenced-file-only change.
2. Typeship resolves one immutable Spec Revision, applies Spec patches, runs Diagnostics and compatibility, and creates one Generation per selected Target.
3. Typeship carries code you last merged into the next Draft and includes commits already on that Draft. It merges non-overlapping edits with the new generated files.
4. One pull request opens or updates per changed Target. It shows API changes, preserved custom code, conflicts, and package checks before release.
5. You review and merge the checked commit. Package changes create a Release; your configured repository workflow can then publish it. Changes only to tests or checks carry forward without creating a release.

Typeship delivers through pull requests and does not receive registry credentials. See Publishing for the release workflow.

How changes are detected

Automatic generation is on by default for new Projects. You can turn it off in Project settings or set auto_generate: false through the API.

An unchanged graph is skipped. With automatic generation on, saving Project config regenerates Targets whose effective config changes. Saving a Target's config, Delivery, or check settings regenerates that Target. A Target already queued or running reuses that Generation. With automatic generation off, use Generate now after a configuration change. After generation, Typeship compares the proposed Git tree with the destination's default branch. If they match and no Draft is open, no new commit, branch, or pull request is needed. An existing Draft stays open when regeneration has no changes to generated files, preserving your commits and checks.

The API returns 202 with one queued Generation per selected Target. Poll GET /generations/{generation_id} while it is queued or running. completed means the generated files are saved, and runtime_ms reports how long the run took; inspect the Target's Delivery and Draft for repository progress. A failed Target does not stop its peers. Starting generation again while a Target is queued or running returns that Generation.

The pull request

Each Target has one Draft against the destination’s default branch. Later Generations add ordinary commits to that Draft. Typeship never force-pushes this branch, so repository writers’ commits remain in its ancestry.

The pull request includes:

• Package, proposed version, operation count, compatibility, and warnings.
• API additions, removals, and changes since the last merged destination baseline.
• Changes to exports, executable names, MCP registry identity, and other package entry points.
• Removed generated files and release notes.
• Build, package creation, entrypoint, your configured package checks, and required repository checks for the latest commit.
• Preserved custom code or an explicit conflict report.

Release readiness applies to the latest commit on the Draft. When you push a commit to the Draft, Typeship integrates it and runs the checks again. Typeship adds commits to the branch and never rewrites its history. If someone rebases or force-pushes the Draft, the next Generate keeps the old branch and opens a new Draft that carries its code forward. Overlapping changes need a conflict decision. A rewritten default branch requires history recovery approval. Put destination-owned security policy and community files on the default branch. Put package code and tests on the Draft when they should ship with the Target.

How code is merged

Typeship compares the files it generated for the last package you merged with the files from the new Generation. It carries your merged package code forward, including changes on the default branch and commits already on the Draft. Changes only to tests or checks also carry forward even though they do not create a release.

Non-overlapping text edits merge automatically. Typeship stops for review when both sides edit the same text region, generated output collides with a file you added, one side deletes a file the other changes, or both sides make incompatible changes to binary content, executable permissions, or symbolic links. Typeship reports the conflict without inserting conflict markers into your files.

Small edits to large generated files can merge automatically. A heavily rewritten file can exceed the automatic merge limit; Typeship reports too_large_to_merge and requires an explicit resolution. This status does not mean the edits overlap.

On a first generation into a non-empty directory, existing files at generated paths, such as README.md, package.json, or .gitignore, require an ownership decision. Review each conflict and choose which version to keep. Existing files at other paths are preserved.

Read the Draft PR description for affected files and base-to-generated diffs. GET /drafts/{draft_id}/files?filter=conflicted lists each conflict with its kind and source, which distinguishes default-branch changes from newly generated code, and GET /targets/{target_id}/draft/files/content returns each side as text or binary bytes. Choose which side to keep explicitly. If you edit and commit a resolved file, inspect the refreshed Draft and approve its yours side. A repository commit alone, including a formatter update, does not approve a conflict. When every conflict has a decision, Typeship continues the Draft and refreshes checks. Typeship merges Draft commits, default-branch changes, and newly generated files in order. It stops at the first conflict, so resolving one conflict can reveal another.

A previous resolution applies only to the same Target, file, conflicting content, and kind of conflict. If any of those change, review the new conflict again. An adopted package has no last merged package, so its first Draft requires explicit review of what to keep.

Typeship installs a per-Target package workflow and manifest. Generated checks cover build, package creation, and public entrypoint loading by default. Configure package checks to add commands run in the Target directory and names of existing repository checks, preserving the entire stored configuration. A commit containing only your edits triggers these checks even when generation output is unchanged. If the same tree is already on the default branch, Typeship reuses checks only from a previously reviewed Draft for the same package contents and check configuration; a first integration with no such evidence reports not assessed and requires checks before release.

When a merged change is confined to tests or check infrastructure (test/, tests/, __tests__, language test-file conventions, repository workflow configuration, or .typeship/) and generated files are unchanged, Typeship carries that code into later Drafts without creating a Release, changing the package version, or starting registry publishing. Runtime code, package metadata, exports, and documentation still need a release.

Compatibility is compared with the latest release, regardless of registry publishing status. An unavailable comparison is unknown. A known API break approved on its source pull request needs no second approval on the Draft when the version bump is sufficient. For an unknown comparison or a break without source approval, a repository writer applies typeship:breaking-approved to the Draft after review. The label never waives an insufficient version bump. The release records the approval source, reviewer, commit, reason, and time.

Older Generations cannot overwrite a newer Draft or reopen one that has merged. If the destination changes unexpectedly during delivery, Typeship reports failure; inspect the Generation and regenerate against the current destination.

Known limits

• Typeship does not infer renames or moves. It evaluates the old and new paths independently, which can produce a delete/change or ownership conflict.
• A resolution is reusable only within the same Target. Equivalent files in another Target need their own review.
• The Console can choose either side of a conflict, but it does not provide a browser code editor. Edit and commit a manual merge on the Draft, or use the CLI/API side-selection actions.
• There are no protected-region markers inside files. Non-overlapping text hunks merge; overlapping hunks stop for whole-file review.
• Shared monorepo lockfiles, workspace configuration, and other paths outside a Target directory remain repository-owned. Typeship does not discover shared dependencies automatically; configure repository-required checks that prove them on each relevant Draft.
• One-shot generation and downloaded files have no merged repository code for Typeship to carry into later runs.

Release notes

Release notes describe the cumulative API and package changes since the last merged release. They come from the surface comparison, not source commit messages. Package-only breaks, such as a removed executable, appear even when API operations are unchanged.

The Draft shows the change summary and writes one plain Markdown entry near the top of the Target's CHANGELOG.md. Typeship tracks that entry while the release is pending. Your heading, other text, and earlier release entries remain yours. You can edit the pending entry; Typeship keeps your text on later Generations and updates only its version heading when the version changes. If you have not edited it, a later Generation can refresh the entry. A test or check change does not add an entry. When publishing is enabled, the GitHub Release uses the same notes from the accepted Target manifest.

For an existing changelog, Typeship inserts the entry before earlier release sections. If the file has no section headings, it adds the entry after the existing text. If the file is a symlink, binary, or the pending version heading cannot be identified, review it before generating a release entry. Typeship synchronizes an advanced default branch into the Draft with a merge commit and never pushes to the default branch.

This illustrative entry describes a change to the fictional Parcel API:

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

### Added
- `shipments.cancel()`: POST /shipments/{shipment_id}/cancel

### Removed (breaking)
- `shipments.archive()`: POST /shipments/{shipment_id}/archive

The destination's committed .typeship/surface.json records the released API surface, package contract, version, and generated paths. A closed, unmerged, or superseded Draft never becomes the comparison point for a release.

The latest release is the most recent versioned Release. A later merge confined to tests or checks changes the code Typeship carries into future Drafts without changing that release. The committed manifest contains no private Organization data. Use the Release to inspect the accepted package and its check results. Registry publishing has a separate status and cannot change the code in the latest release.

For an existing package, review the first adoption Draft to establish which code Typeship should preserve. On later updates, removing a generated file that you changed requires conflict review; an unchanged generated file can be removed automatically.

Breaking changes

Typeship Release checks API compatibility, package compatibility, and version correctness for the Draft. The API exposes these as separate values. An unavailable analysis produces an error; the first tracked release establishes the initial comparison baseline.

Package compatibility includes SDK source declarations and your accepted custom code. Renaming an exported request type can break customer code even when the HTTP request stays the same. Typeship checks the latest release package against the combined Draft and includes confirmed source breaks in the required version bump.

Source checks cover declarations, not all runtime behavior. Unresolved type changes, missing dependencies, dynamic Python exports, platform-specific Go declarations, or incomplete historical code make the affected comparison unknown. A version bump alone does not resolve that uncertainty. Review the reported declarations and use the compatibility approval described above when you accept an unresolved comparison.

Every package change needs a new version; a change confined to tests or check infrastructure does not:

Versions and prerelease identifiers cannot move backward. 1.0.0-beta.2 follows 1.0.0-beta.1, and stable 1.0.0 follows its prereleases. A byte-identical result creates no version change. A Draft update replaces its active entry without adding a duplicate.

Make Typeship Release a required destination check to prevent a Draft with an invalid version from merging. It is advisory by default. For an intentional API break, follow Release a breaking change.

URL sources receive destination review but no source pull-request preview. Several source changes can merge while a destination Draft remains open; they accumulate against the last merged destination release.

Destinations

Configure each Target's Deliveries independently. If no repository is configured or GitHub access is missing, successful generation remains available to download even when delivery cannot open a pull request.

Disabling a Target or changing its repository or directory retires its previous Draft: readiness fails and the old pull request closes. Typeship deletes the old release branch only if nobody has pushed to it since Typeship's last commit. Already merged files remain; remove them explicitly in the repository if needed.

Manual regeneration

Use Generations → Generate now or POST /api/v1/projects/{project_id}/generate to run the same workflow on demand. Inspect each Target Draft for pull-request and delivery state.

Where custom code belongs

For a linked repository Delivery, custom exports, helpers, tests, and build changes can live in the generated package. Commit them to the Draft and make their requirements explicit in the Target's checks. Typeship preserves non-overlapping changes across later Generations and calls out ambiguous ownership instead of overwriting it. A separate wrapper is still useful when application-specific code should release independently. See Customize generated packages.

Versioning

Package versions belong to each Target. Typeship selects the minimum version required by the cumulative Draft; you can select a larger version. Merging a checked Draft with package changes advances the latest release; a merge confined to tests or checks only changes the code Typeship carries into the next Draft. OpenAPI info.version and GraphQL metadata describe the API, not package releases. See Choose the Draft version.