Connect GitHub ~ SHIP

Install the SHIP GitHub App so agents can open pull requests, read your CI, and respond to review feedback.

Overview

Every project needs the GitHub App, whichever way you hand work over. SHIP opens pull requests in your repository, gets CI results from it and reads review feedback from it.

The app can also be the project's tracker. If you choose GitHub Issues, the same installation does both jobs, and you do not make a second connection.

Steps

Install the App

During onboarding, click Connect GitHub. The console sends you to GitHub to install the app on your organization. There, choose the repositories that SHIP can work in.

After the install, GitHub asks you to authorize the app for your own account. SHIP uses that authorization to check that your account can reach the install before it connects the install to your organization. A new organization gets its free credits from this check, one time for each GitHub account.

You can also install the app from GitHub Marketplace or from its page on GitHub. GitHub then sends you to SHIP. Sign in, and SHIP connects the install to the organization that you work in.

The app asks for these permissions:

Contents, read and write, to clone the repository, push the agent's branch and merge when you turn on auto-merge.
Pull requests, read and write, to open pull requests and post reviews and comments on them.
Issues, read and write, to comment on issues and set ship:* labels when GitHub Issues is the tracker.
Actions, read and write, to read CI runs and their logs, and to start the preview workflow that your ship.yml names.
Checks, read and write, to watch CI and run a check suite again when it was cancelled.
Deployments, read only, to get the preview address from the deployment that your workflow creates.
Workflows, read and write, to push a change under .github/workflows/, which SHIP does only when you ask for it.
Commit statuses, read only. SHIP does not read them yet.
Metadata, read only, which GitHub gives every app.

Install the app only on the repositories that you want SHIP to work in, not on all of them. To add more repositories later, change the permissions on the installation. You do not have to onboard again.

Point a project at a repository

Each SHIP project uses exactly one repository. You choose it on the project step of onboarding, together with where that project's work is planned.

Verify

The onboarding page marks the step complete after you return from GitHub with the installation and select a repository.

What the agents do with it

Create a work branch from your base branch, which is main unless the project's ship.yml sets baseBranch.
Run your formatter, linter, typecheck and tests before each push, so the first CI run is not the first check.
Open a pull request that describes the work and links back to the issue, if there is one.
Watch CI. If CI fails, the Builder gets the logs and works on a fix, and the mission does not stop. Retry limits decide how long that continues.
Read a review that requests changes, and fix what it asks for.
Post the review and QA verdicts on the pull request.

By default, you do the merge. The agents prepare everything and stop at a pull request that a human accepts. Auto-merge is an explicit opt-in, per project or per mission, for work that you decide does not need that gate. It stays off until you turn it on.

note

Two limits are important. The QA agent holds a read-only token, so it cannot push. A change under .github/workflows/ needs your instruction: SHIP checks every change before the commit exists and blocks a CI change that you did not ask for.

Troubleshooting

The agent can't push

At github.com/settings/installations, check that the installation has Contents read and write for that repository. The owner of the installation must accept a newly granted permission before it takes effect.

CI never reports back

SHIP watches check_suite.completed. Make sure that your workflows run on pull_request events. A workflow that runs only on push to the default branch gives SHIP no result for the pull request.

A pull request sits with no checks at all

A pull request with conflicts against its base produces no check runs, so SHIP has nothing to wait for. Resolve the conflict, and CI starts.

Connect GitHub