> For the complete documentation index, see [llms.txt](https://docs.aviator.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aviator.co/verify/reference/github-integration.md).

# GitHub integration

Reference for how Verify integrates with GitHub.

### GitHub App

Verify uses the Aviator GitHub App for repository access. Install it from the Aviator UI under **Settings → Integrations → GitHub**, or directly from the GitHub Marketplace.

#### Permissions

The app requests the permissions needed to read code, post checks, and surface verification results on PRs:

| Permission          | Access     | Why                                             |
| ------------------- | ---------- | ----------------------------------------------- |
| Repository contents | Read       | Read the diff and source for verification       |
| Pull requests       | Read/Write | Surface verification context on PRs             |
| Checks              | Read/Write | Create and update the `aviator/verify` PR check |
| Metadata            | Read       | Basic repository info                           |

If you don't see Verify behaving as expected, the most common cause is that the GitHub App doesn't have access to the repo. Change access in GitHub under **Organization Settings → Installed GitHub Apps → Aviator → Configure**.

### The PR check

Every verification run is mirrored to GitHub as a single PR check.

* **Check name:** `aviator/verify`
* **Where it shows up:** the PR's "Checks" tab and the merge-readiness summary.

#### Check states

The check state tracks the verification run's status:

| Verification run status | GitHub check state | Notes                                                  |
| ----------------------- | ------------------ | ------------------------------------------------------ |
| `pending`               | `queued`           | Run is enqueued but hasn't started.                    |
| `in_progress`           | `in_progress`      | Run is executing.                                      |
| `passed`                | `success`          | All criteria passed or were waived.                    |
| `failed`                | `failure`          | At least one criterion failed without a waiver.        |
| `error`                 | `failure`          | The run itself errored — surfaced as a check failure.  |
| `deferred`              | `in_progress`      | Waiting for invariant selection before the run starts. |

The check summary links back to the runbook in the Aviator UI for the full review document.

### Branch protection

To require verification before merge, add `aviator/verify` to your repo's branch protection:

1. Repository **Settings → Branches → Add rule** (or edit an existing rule for your protected branch).
2. Enable **Require status checks to pass before merging**.
3. Search for and select **aviator/verify**.

Recommended settings:

```
☑ Require status checks to pass before merging
   ☑ aviator/verify
☑ Require branches to be up to date before merging (optional)
```

See [Configuring branch protection](/verify/how-to-guides/configuring-branch-protection.md) for the step-by-step.

### See also

* [Configuring branch protection](/verify/how-to-guides/configuring-branch-protection.md)
* [Connect a repository](/verify/how-to-guides/connect-a-repository.md)
* [Understanding verification results](/verify/reference/understanding-verification-results.md)
* [Slack notifications](/verify/reference/slack-notifications.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.aviator.co/verify/reference/github-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.