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

# Connect a repo

> Link a GitHub repo to a Qodex project so Qodex can analyze code and review pull requests.

# Connect a repo

Connect a GitHub repo to a Qodex project after the GitHub App is installed.

Once connected, Qodex can read the repo, build an initial code map, and review future pull requests.

## Prerequisites

* The Qodex GitHub App is installed on the account that owns the repo. See [Install the GitHub App](/pr-review-install-github-app).
* The install is granted to your Qodex project. New installs are granted automatically; existing installs may need to be re-granted from the project.
* You have not hit the 10-repo cap on the project.

## 1. Open the GitHub integration panel

In your project, open **Settings > Integrations > GitHub**.

The Connected accounts panel lists every GitHub install granted to this project, including the account login, repo count, and Disconnect button.

## 2. Add a repo from an existing install

Click **Add a repo from existing install**.

Qodex queries each granted install for the repos it can see and groups them by account. The picker shows only repos visible to that GitHub App install, not every repo on your GitHub account.

If your install is on "Only select repositories" mode and the repo you want is not listed, open the install on GitHub and add the repo there first; the picker will pick it up on next open.

## 3. Pick the repo

Click the repo you want to connect. Qodex fetches its metadata and checks two limits before linking it.

* **Repo size cap**: 500 MB. Repos over the cap are refused with "Repo {full_name} is {size}MB, exceeds 500MB cap. Subdirectory selection for monorepos is planned for v2."
* **Project repo cap**: 10. Hitting the cap returns "Project already has 10 linked repos (max). Unlink one before adding another."

When both checks pass, Qodex links the repo and queues a background analysis job.

## 4. Wait for analysis

The first analysis clones the repo and walks it to build the initial code map. The repo card reports `pending`, `running`, `success`, or `failed` while it runs.

Later PR reviews are faster because Qodex only needs the PR diff, not a full fresh clone.

## Sharing a repo across projects

The same repo can be linked from multiple Qodex projects. If two projects link the same repo, each project gets its own review, Check Run, findings, and spend. Reviews do not see each other.

## Access guarantees

The GitHub App requests `Contents: read`, `Pull requests: write`, `Issues: write`, `Checks: write`, and `Metadata: read`. Qodex never requests write access to your code. PR reviews and inline comments are written through the Pull requests scope, not through commits. Qodex will not modify, push, or rewrite your code.

The clone is encrypted at rest and is rebuilt on demand. Disconnecting the install or unlinking the repo drops the cached clone.

## Manual refresh

When a repo's contents change in a way Qodex should pick up outside the normal PR flow (a force-push to default, a large rebase, a new submodule), click **Refresh analysis** on the repo. The clone-and-analyze pipeline runs again. The button is rate-limited to once per hour per repo.

## Try it yourself

<CardGroup cols={2}>
  <Card title="Open a PR" icon="git-pull-request" href="/pr-review">
    Open any PR on the linked repo. Qodex reviews on the next event.
  </Card>

  <Card title="Trigger a manual review" icon="terminal" href="/pr-review-slash-commands">
    Comment `@qodex review` on an existing PR.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Walkthrough anatomy" icon="message-square" href="/pr-review-walkthrough-anatomy" />

  <Card title="Disconnect an install" icon="unplug" href="/pr-review-disconnect" />
</CardGroup>