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 this one. Pull requests land in your repository, CI results come back from it, and review feedback is read from it, so the GitHub App is required whichever way you hand work over.

It can also be the project's tracker. Choose GitHub Issues and the same installation carries both, with no second connection to make.

Steps

Install the App

During onboarding, click Connect GitHub. You are sent to GitHub to install the app on your organization, where you choose the repositories SHIP may work in.

The app asks for four permissions. Contents, read and write, so it can clone the repository and push the agent's branch. Pull requests, read and write, to open them and read review threads. Checks and Actions, read only, to watch CI and read a failing run's logs. Issues, read and write, which is needed only if you use GitHub Issues as the tracker.

Install it on the repositories you want covered rather than all of them. Adding more later is a permissions change on the installation rather than a re-onboarding.

Point a project at a repository

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

Verify

The onboarding page marks the step complete once the installation is back and a repository is selected.

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 pushing, so the first CI run is not the first time anything was checked.
Open a pull request describing the work, linked back to the ticket where there is one.
Watch CI. A failure goes back to the builder with the logs, and it works the failure rather than ending the mission. Retry limits decide how long that continues.
Read review threads and address blocking comments.
Mark the pull request ready once review and QA are satisfied.

Merging is yours by default. The agents prepare everything and stop at a pull request a human accepts. Auto-merge exists as an explicit opt-in, per project or per mission, for work where you have decided you do not need that gate, and it stays off unless you turn it on.

note

Two boundaries are worth knowing, because the credentials enforce them rather than the instructions. The QA agent holds a read-only token and has no way to push. And no agent holds a credential that can edit your CI configuration: a change under .github/workflows/ is blocked before the commit is created, unless you explicitly authorized it.

Troubleshooting

The agent can't push

Check the installation has Contents read and write for that repository at github.com/settings/installations. A newly granted permission also has to be accepted by whoever owns the installation before it takes effect.

CI never reports back

SHIP watches check_suite.completed. Confirm your workflows run on pull_request events, because a workflow that only runs on push to the default branch produces nothing for a pull request to gate on.

A pull request sits with no checks at all

A pull request with conflicts against its base produces no check runs, so there is nothing to wait for. Resolving the conflict lets CI start.

Connect GitHub