> ## Documentation Index
> Fetch the complete documentation index at: https://qodex.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub integration for PR reviews

> Connect GitHub repositories to Qodex so the agent can read code, review pull requests, and sync generated tests.

# GitHub

The GitHub integration lets Qodex understand your repository and participate in pull request review.

After you install the Qodex GitHub App and link a repo to a project, Qodex can inspect code, run PR review workflows, post inline findings, publish Check Runs, and sync generated tests when you choose to send them back.

## What Qodex can do with GitHub

| Capability                 | What it means                                                                       |
| -------------------------- | ----------------------------------------------------------------------------------- |
| Read repository code       | Qodex can clone and analyze linked repos so reviews and tests have project context. |
| Review pull requests       | Qodex can post a walkthrough comment, inline findings, and a Check Run.             |
| Route one repo to projects | A GitHub install can be granted to more than one Qodex project.                     |
| Sync tests                 | Generated scripts can be pushed through the opt-in Sync to GitHub flow.             |

Qodex cannot push arbitrary commits, change repo settings, or merge pull requests.

## How setup works

### 1. Install the GitHub App

Install the Qodex GitHub App on the account or organization that owns your repo. Choose the repositories Qodex is allowed to access.

Qodex uses short-lived GitHub App installation tokens, not a personal access token.

### 2. Link a repo to your Qodex project

In Qodex, open **Settings > Connections > GitHub** and choose a repo from the picker.

The project can link up to 10 repos. Repos larger than 500 MB are rejected at link time.

### 3. Let Qodex analyze the repo

After linking, Qodex starts a background analysis job. It reads the repo, discovers routes and project structure, and seeds project memory so later agent work has useful context.

You can manually refresh a linked repo later. Refreshes are rate-limited to avoid repeatedly cloning the same repo.

## Unlink a repository

Open **Settings > Connections > GitHub**, find the linked repository or folder, click **Unlink**, and confirm **Unlink**. This removes the repository's association with the current Qodex project and drops Qodex's cached clone. It does not delete the GitHub repository or uninstall the GitHub App.

To remove the project's grant to an entire GitHub App install instead, see [Disconnect a GitHub account](/docs/pr-review-disconnect).

## Pull request review

When PR review is enabled, Qodex reacts to PR activity through GitHub webhooks.

For each tracked PR, Qodex can:

* Read the PR diff and relevant surrounding code.
* Post a walkthrough comment.
* Add inline findings where the issue appears.
* Run verification probes when needed.
* Publish a Check Run that can be used for merge gating.

<CardGroup cols={2}>
  <Card title="Install the GitHub App" icon="git-branch" href="/docs/pr-review-install-github-app">
    First-time install for an account or organization.
  </Card>

  <Card title="How a review fires" icon="webhook" href="/docs/pr-review-how-it-fires">
    See the webhook-to-review lifecycle.
  </Card>

  <Card title="Check Run and merge gating" icon="shield-check" href="/docs/pr-review-check-run">
    Use review status in your PR rules.
  </Card>

  <Card title="Limits and caveats" icon="circle-alert" href="/docs/pr-review-limits-caveats">
    Understand diff limits, costs, drafts, and opt-out behavior.
  </Card>
</CardGroup>

## Permissions

The GitHub App requests the permissions needed for review:

| Permission          | Why Qodex needs it                    |
| ------------------- | ------------------------------------- |
| Contents read       | Clone and inspect files.              |
| Metadata read       | List and identify repositories.       |
| Pull requests write | Post PR comments and inline findings. |
| Checks write        | Publish Check Runs.                   |

Generated tests are synced only when you trigger the sync flow from Qodex.

## Next steps

<CardGroup cols={2}>
  <Card title="PR review overview" icon="git-pull-request" href="/docs/pr-review">
    Learn the full PR review workflow.
  </Card>

  <Card title="Sync tests to GitHub" icon="upload" href="/docs/syncing-tests-to-github">
    Send generated tests back into your repo.
  </Card>

  <Card title=".qodex.yaml reference" icon="file-code" href="/docs/qodex-yaml-reference">
    Configure repo-level PR review behavior.
  </Card>

  <Card title="Integrations" icon="plug" href="/docs/integrations">
    Return to all integrations.
  </Card>
</CardGroup>