> ## 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

> 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 > Integrations > 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.

## 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="/pr-review-install-github-app">
    First-time install for an account or organization.
  </Card>

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

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

  <Card title="Limits and caveats" icon="circle-alert" href="/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="/pr-review">
    Learn the full PR review workflow.
  </Card>

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

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

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