Integrations
GitHub
What the Stableship GitHub App can do in your repositories, what starts a check, and how releases are held.
Install the app
During setup, Stableship asks you to install the Stableship GitHub App and choose which repositories it can read. You can change the selection on GitHub at any time. If your organization requires approval, the request goes to an organization owner first. See Connecting GitHub for the common snags.
What it can do
| Permission | Access | What Stableship uses it for |
|---|---|---|
| Contents | Read | Reading your code to draft your rules and build the private copy |
| Metadata | Read | Listing the repositories you selected |
| Checks | Read and write | Posting the Stableship check on each push |
| Pull requests | Read and write | Replying on pull requests. It never opens, changes or merges one |
| Deployments | Read and write | Answering deployment protection, to hold or release a deploy |
| Issues | Read | Hearing /gate comments on pull requests |
The app cannot write code and has no access to your workflows. Stableship never pushes, opens pull requests or merges. Your coding agent writes every fix.
What starts a check
- Every push, and every pull request that is not a draft. Pull requests from forks are never checked.
- A push to your default branch also re-checks the problems still open, and resumes an audit that was on hold.
- A check you or your agent start from the app, the CLI or the MCP server.
Stableship picks the scope from what the change touched. See How Stableship works.
Ask for a scope
Add a Gate: trailer to the last commit you push:
Fix the invoice query Gate: security payments changedThe scopes are quick, security, qa, full and skip, followed by an optional reason. A push with a trailer is checked at once rather than batched with other pushes.
On a pull request, comment /gate <scope> [reason] (for example /gate full before launch) to check its latest commit again at that scope. Only the repository's owner, members and collaborators can do this, and Stableship replies with a link to the run.
Asking for more is always honoured. Asking for less than your project's minimum for that change (a migration, billing or sign-in code) runs at the minimum, and the check says so.
The Stableship check
Each checked commit gets a check named Stableship. While it runs, it says what it is testing and roughly how long is left. When it finishes, it shows the verdict and links to the release in Stableship.
Hold releases
On Protect, a release that breaks one of your rules is held until it is fixed or someone ships it anyway. Holds go through GitHub deployment protection:
- In the repository on GitHub, open Settings, then Environments, then production.
- Under deployment protection rules, enable Stableship AI.
- If GitHub asks you to accept updated permissions for the Stableship GitHub App, accept them.
Hosts that deploy from GitHub Actions instead (Railway, Fly and others) can wait for the verdict in the workflow: see Gate deploys in CI.
Disconnect
Uninstall the Stableship GitHub App, or remove repositories from it, in your GitHub settings under Applications. Delete workspace in Stableship's Settings also uninstalls it.
For your coding agent: this page as Markdown