GitHub
Connect the repository that holds your API spec and the repositories your packages live in, then review API changes and release each package through pull requests.
The Typeship GitHub App works with two kinds of repository:
- The API repository holds your OpenAPI or GraphQL spec. Pull requests that change the spec get a review before they merge.
- A package repository holds one generated CLI, MCP server, or SDK. Each Target delivers to a package repository and keeps one Draft pull request open there with its next release.
FreeAvailable on every planOne linked API, every selected package, and the full pull-request workflow are included on Free.
Choose a repository layout
Each Target delivers to a repository and a directory. Give each Target its own repository unless you have a reason to share one.
| Layout | Tags | When to use it |
|---|---|---|
| One repository per Target | v1.2.3 | Recommended. Each package has its own history, issues, and release list, which is what package users expect. |
| One repository, a directory per Target | <package>-v1.2.3 | You want every package in one place. Directories cannot overlap. |
| Packages inside the API repository | <package>-v1.2.3 | You want the fewest repositories. Spec reviews and package Drafts share one pull request list. |
A Target at the repository root uses plain vX.Y.Z tags. A Target in a subdirectory prefixes its tags with its component name so Targets that share a repository never collide.
Connect GitHub
Install the GitHub App
In Create project, choose GitHub as the Spec source and select Connect GitHub. Install the App on the account or organization that owns the API repository. The installation joins the Typeship organization you are signed in to.
If your package repositories belong to another account or organization, install the App there too. One Typeship organization can hold several installations.
Select the API repository and spec
Choose the repository, then enter the Spec file path, such as openapi.yaml. Typeship follows every document that file references inside the repository.
Choose Targets and create the Project
Turn on the CLI, MCP server, and SDKs you want, name the Project, and create it. Typeship generates each Target right away. Nothing is written to GitHub until a Target has a repository.
Connect each Target's repository
Open each Target and select Connect repository. Choose the package repository, a Directory (blank means the repository root), and the package name or Go module path. Typeship opens the Target's first Draft in that repository.
If the repository is missing from the list, select Update GitHub App access and grant the App access to it in GitHub.
Require the checks
Typeship cannot change branch protection. Add the status names to each repository's rulesets.
typeship projects create --help for the repository source and Targets. In the API, a Target's repository is its Delivery: POST /deliveries with type: "repository" and the repository identifier and directory.Review an API change
When a pull request in the API repository changes the spec, Typeship generates every Target from the pull request's commit and posts one sticky comment with:
- API compatibility and blocking issues;
- breaking changes grouped by who they affect;
- one result for each Target; and
- warnings, coverage, and the analyzed commit.
It also sets two statuses:
Typeship API Reviewcovers compatibility and blocking issues. An intentional breaking change stays marked as breaking, and a reviewer with write access can approve it with thetypeship:breaking-approvedlabel.Typeship Previewsconfirms that every Target generated. It is separate so a generation failure is not mistaken for an API policy failure.
A pull request that does not change the spec passes both statuses without a new comment.
When the pull request merges, Typeship regenerates every Target from the default branch and updates each Target's Draft. Turn off Automatic regeneration in Project settings to regenerate only when you ask.
Release a package
The Draft
Each Target has one Draft: an ordinary pull request in its package repository, on a typeship/update-<target>-... branch. Typeship keeps it current as the spec changes. It shows:
- the proposed version and the minimum version bump the changes require;
- API and package changes since the last release;
- removed files and warnings; and
- the release notes for the proposed version.
Merging the Draft releases that version. The next change opens a new Draft on a fresh branch.
If the generated files already match the repository, Typeship reports no changes and does not open a pull request.
Choose the version
Typeship proposes the smallest version the changes allow. To choose a larger one, rename the Draft pull request to exactly release: X.Y.Z, or set it on the Target in the console or API. Renaming requires write access to the repository. Typeship Release fails if the version is smaller than the changes require and names the minimum.
Customize the package
Commit changes to the package directly on the Draft branch. Typeship keeps your commits and merges them with newly generated files on the next generation. Put repository-wide files, such as security policy and community files, on the default branch.
If the Draft's history is rewritten, Typeship opens a new Draft and keeps the old branch. A rewritten default branch needs history recovery approval before generation continues.
Files Typeship writes
Besides the generated package, the Draft proposes these files. You own them once merged.
| Path | Purpose |
|---|---|
<directory>/CHANGELOG.md | One entry for the pending release, added above your earlier entries. Other text in the file stays as you wrote it. |
.github/workflows/typeship-<target>-checks.yml | Runs the Target's package checks on the Draft. |
.typeship/run-package-checks.mjs and .typeship/targets/<target>-checks.json | The check runner and each Target's check commands. |
<directory>/.typeship/surface.json | The accepted API and package surface that later Drafts compare against. |
.typeship/targets/<target>.json | The accepted version, tag, release notes, and registries. Only with Publish after merge. |
.github/workflows/typeship-release.yml and typeship-republish.yml | Publish an accepted release, and retry one. Only with Publish after merge. |
.typeship/README.md | Describes these files and the release flow. |
Publish after merge
With Publish after merge turned on for a Target, merging its Draft starts typeship-release.yml in that repository. The workflow creates the tag and a GitHub Release with the accepted notes, then publishes to npm, PyPI, the Go module proxy, or the MCP Registry.
The release workflow runs in your repository with your registry credentials or trusted publishing. Typeship never receives registry credentials. See Publish your packages.
Require the checks
Add these names to each repository's required status checks:
| Repository | Required check | What it prevents |
|---|---|---|
| API repository | Typeship API Review | Unapproved breaking changes or blocking issues |
| API repository | Typeship Previews | Spec changes that fail to generate a Target |
| Package repository | Typeship Release | A Draft whose version does not match its changes, or whose package checks failed |
Typeship Release includes the result of the Typeship / <target> / package checks run from the checks workflow, so you only need to require Typeship Release.