--- title: "GitHub" description: "Connect your API and package repositories for change review, automatic generation, and release pull requests." url: https://typeship.dev/docs/integrations/github markdown: https://typeship.dev/docs/integrations/github.md section: "Get started" --- > ## Documentation index > Fetch the complete documentation index at https://typeship.dev/llms.txt (every page, one line each) or the full text at https://typeship.dev/llms-full.txt. > Append .md to any docs URL, or send Accept: text/markdown, for the markdown twin of that page. # GitHub Connect your API and package repositories for change review, automatic generation, and release pull requests. The Typeship GitHub App connects the API contract you already keep in GitHub to the CLI, MCP server, and SDK packages you want Typeship to maintain. Pull requests against the API contract review the change before it merges. After merge, each changed package receives its own release pull request in its destination repository. _Available on every plan. One linked API, every selected package, and the complete pull-request workflow are included on Free._ ## Connect GitHub 1. **Install the GitHub App** Open the Project's **Definition** page. Under **Definition source**, choose **GitHub repo**. Install the Typeship GitHub App on the account or organization that owns the repository. Grant access to the API repository. You can select all repositories or choose individual repositories in GitHub. If source and destination repositories belong to different GitHub accounts or organizations, install the App in each and connect both installations to the same Typeship organization. 2. **Select the API contract** Enter the repository as `owner/repository`, then select the OpenAPI or GraphQL entrypoint. Typeship follows the complete connected contract, including referenced documents. 3. **Add package destinations** Choose a repository and directory for each generated package. A CLI, MCP server, or SDK can use the API repository or a dedicated package repository. Install the App on every GitHub account or organization that owns a destination. 4. **Generate and enable updates** Run the first generation and review the destination pull requests. When the packages look right, enable **Automatic generation** in Project settings. Add the Typeship statuses to GitHub branch protection if they should block merging. > **For AI agents:** Use > > `typeship projects create --help` > > for the repository source and initial generated products. In the API, those products are > > `targets` > > and their destinations are > > `deliveries` > > . ## Source review and destination release Typeship publishes different information in the API source repository and generated-package repositories: | Repository | Question being answered | GitHub surface | | ------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------- | | API source | Is this API change understood and approved? | One sticky report, `Typeship – API change review`, and `Typeship – Preview Generations` | | Package destination | Is this exact generated package ready to release? | Release pull request, changelog, and `Typeship – release readiness` | The Console provides the cross-repository view. Public pull requests contain only what their reviewers need, without billing, Project settings, or private Console links. ### Review an API change When a pull request changes the linked API contract, the sticky report shows: * API compatibility and blocking issues; * breaking changes grouped by consumer impact; * one result for each generated product; and * warnings, coverage, and the analyzed commit. `Typeship – API change review` covers compatibility and blocking issues. An intentional breaking change still appears as breaking, but an authorized reviewer can acknowledge it with the `typeship:breaking-approved` label. `Typeship – Preview Generations` confirms that every configured Target generated successfully. It remains separate so API-policy and generation failures are not collapsed into one check. A pull request that does not change the linked API contract passes both statuses without adding a comment. ### Release a generated package After an API contract change merges, Typeship opens or updates one release pull request per changed package. It includes: * the proposed version and required version bump; * API and published-package changes; * removed generated files and warnings; and * an updated `CHANGELOG.md`. `Typeship – release readiness` checks the exact generated commit and the cumulative change since the last release merged in that destination. If the version is too small, the status names the minimum required version. Do not commit directly to a Typeship release branch. A human commit makes release readiness fail. Put repository-owned CI, security policy, and community files on the default branch, then regenerate. If the generated tree already matches the destination, the Generation reports **Destination current** and does not open a pull request. > **Note** > Typeship publishes packages through reviewed GitHub pull requests. Your repository's release workflow publishes to npm, PyPI, or a Go module registry after merge. Typeship never receives your registry credentials. ## Require the checks Typeship cannot change branch protection. Add these status names to the relevant GitHub ruleset: | Repository | Required status | What it prevents | | ------------------------ | -------------------------------- | ------------------------------------------------------------------ | | API source | `Typeship – API change review` | Unapproved breaking changes or blocking issues | | API source | `Typeship – Preview Generations` | API changes that fail to generate a configured Target | | Each package destination | `Typeship – release readiness` | Edited candidates or versions that do not match the release impact | Typeship uses commit statuses instead of requesting GitHub's broader Checks permission. Each status links to the public pull request it evaluates. ## Details ### GitHub App permissions The GitHub App requests four repository permissions: | Permission | Why Typeship needs it | | ------------------------ | --------------------------------------------------------- | | Contents: read and write | Read API contract documents and create generated branches | | Pull requests: write | Open release pull requests and update the source report | | Commit statuses: write | Publish API review, generation, and release decisions | | Metadata: read | Identify repositories and default branches | Repository selection remains under your control in GitHub. Public readability never grants Typeship permission to write. Typeship authenticates GitHub events, reads pull requests at immutable commits, and verifies that an analysis is still current before publishing it. It never executes code from a customer repository. ### Troubleshooting | Symptom | What to do | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | **Destination current** and no pull request | Nothing. The generated tree already matches the destination. | | Generation succeeded but delivery failed | Open the Generation and follow its Delivery message. Confirm the App can write to that repository, then regenerate. | | Status appears but does not block merging | Add the exact status name to the repository's required checks. | | API contract path was renamed | Update the entrypoint in Project settings. | Project settings shows source readability, destination access, the latest GitHub event, and the status names used by each repository. ## Continue reading - [Preview Generations](https://typeship.dev/docs/projects/preview-generations): See how source pull requests report compatibility, blocking issues, and package results. - [Regeneration](https://typeship.dev/docs/projects/regeneration): Understand destination candidates, changelogs, and release baselines. - [Release a breaking change](https://typeship.dev/docs/guides/release-a-breaking-change): Approve the source change and version each affected package. ## Sitemap [Every page of these docs](https://typeship.dev/llms.txt)