# 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](/docs/help/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](/docs/concepts#audits-and-checks).

## Ask for a scope

Add a `Gate:` trailer to the last commit you push:

```text
Fix the invoice query

Gate: security payments changed
```

The 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:

1. In the repository on GitHub, open **Settings**, then **Environments**, then **production**.
2. Under deployment protection rules, enable **Stableship AI**.
3. 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](/docs/guides/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.