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

# GitHub

GitHub is Capy's primary integration. The GitHub App gives your threads repository access, lets Capy open pull requests, and delivers the webhook events (CI results, review feedback, comments, merges) that wake the owning thread without you relaying anything. Connect it first; most of Capy's autonomy depends on it.

## Connect GitHub

<Steps>
  <Step title="Install the GitHub App">Go to [Settings → Integrations → GitHub](https://capy.ai/settings/integrations/github) and install the Capy GitHub App on your GitHub account or organization. Grant access to all repositories or a selected set; you can change the selection later in GitHub's own app settings.</Step>
  <Step title="Attach repositories to a project">Add the repositories a project should work in. Threads in that project clone them automatically when a machine starts.</Step>
  <Step title="Connect your personal GitHub account">Link your own GitHub account in the same settings page. With it connected, commits Capy makes on your behalf carry your name and pull requests open as you; without it, both are attributed to the Capy app.</Step>
</Steps>

## How Capy authenticates

No GitHub token ever sits on the machine. The machine holds a short-lived signed grant (Capy's own credential, useless against GitHub directly), and every `git` and `gh` call routes through Capy's git proxy, which attaches the real GitHub credential server-side per request. Grants live about two hours and refresh automatically; you never manage them.

The practical consequences:

* `git` and `gh` work normally on the machine, including private repos, submodules, and private dependencies the installation covers.
* Public repos and package-manager dependencies work exactly as they would with direct access.
* Anything that expects a raw token fails closed: `curl -H "Authorization: token $GH_TOKEN"` fails because no token exists. Tell the agent to use `gh api` instead; it's the supported path.

Three identities are resolved independently: the commit author is you when your GitHub account is connected (otherwise `Capy Agent`), the pull request author follows your configuration (your account when connected, the app otherwise), and the push itself is always authenticated as the app, which is what branch protection and the events feed show.

## Branches and pull requests

Capy manages branches itself. When a thread publishes work, Capy mints a fresh `capy/` branch, pushes to it, and opens the pull request against the branch the thread started from: the repository default unless you asked for another base. You never check out, name, or clean up working branches, and Capy never pushes to your default branch directly.

If a thread already published to its own `capy/` branch, later publishes reuse it and update the same pull request. Merging happens where you choose: from Capy's pull request view or on GitHub.

## GitHub events wake your threads

Webhook events route to the thread that owns the pull request, so you don't babysit CI or forward feedback:

* **CI.** A failing check wakes the thread immediately (fail-fast), and when the whole check set finishes, the thread gets one consolidated verdict instead of a ping per check.
* **Review feedback.** Your reviews and comments on a Capy-opened PR wake the owning thread by default. Bot feedback is ignored by default; an org admin can allowlist specific bot accounts in settings.
* **Merge.** Merging wakes the thread so it can finish up. A PR closed without merging becomes passive context: the thread sees it next time it runs but isn't woken for it.
* **Conflicts.** A push to the base branch that makes an open Capy PR conflict notifies the owning thread. This only wakes threads that were recently active (3 days by default, configurable), so a base merge can't resurrect months-old threads.

## Talking to Capy from a pull request

Mention Capy in a PR comment, top-level or inline. Mentions require that your GitHub account is connected to a Capy account with active membership in the org; mentions inside code blocks, links, or quoted text don't count.

| You write | What happens |
| - | - |
| `@capy <message>` | The message goes to the thread that owns the PR and wakes it. If no thread owns the PR, Capy starts a new thread in the project attached to the repository. |
| `@capy review` | Starts a review round on the current head. Re-triggering on an already-reviewed head reuses the completed round instead of billing twice. |
| `@capy review <instructions>` | Starts a review round with your trailing text as the run prompt. This forces a fresh round even when the head was already reviewed, so your instructions can't be swallowed by an old result. |

## Auto-review

Auto-review is a per-repository mode set in Settings → Review: **Off**, **Once** (first review when a PR opens), or **Every push**. Drafts are skipped until they're ready and pushed. Enabling it means your org pays for the automatic rounds, and a manual `@capy review` bills the requesting org. [Review](/review) is the main page for modes, rounds, findings, and billing.

## What Capy posts back

* Pull requests, opened from `capy/` branches under the identity you configured.
* Review findings as inline comments at the exact head reviewed, posted as one batch review, covering findings at or above your severity threshold (default medium). Findings below the threshold stay in Capy's own record, where you see everything.
* Thread resolution: when a finding is fixed or dismissed in Capy, the matching GitHub comment thread resolves.

## Permissions

| Permission | Why Capy needs it |
| - | - |
| Contents | Clone, fetch, and push through the git proxy |
| Pull requests | Open PRs, read feedback, post review comments |
| Checks and commit statuses | Receive CI results that wake threads |
| Metadata | List repositories for project attachment |

Repository reach follows the installation: a read-only installation can't write anything, and a repo the installation doesn't cover returns GitHub's own 404.

## Troubleshooting

<AccordionGroup>
  <Accordion title="A repo doesn't appear in Capy">The installation's repository selection controls what Capy can see. Check the Capy app's settings on GitHub and make sure the repo is selected, then re-check the project's repository list.</Accordion>
  <Accordion title="Capy doesn't respond to my @capy mention">Your GitHub account must be connected to a Capy account that's an active member of the org, and the mention must be visible text; mentions inside code blocks, links, or quotes are ignored. Connect your account in Settings → Integrations → GitHub.</Accordion>
  <Accordion title="My thread didn't wake on CI">CI events route to the thread that published the PR. A PR opened outside Capy, or with `gh pr create` instead of Capy's own publish path, may not have an owning thread; ask the thread to create the PR itself.</Accordion>
  <Accordion title="The PR was opened by capy-ai[bot] instead of me">Attribution follows your connected GitHub account. Connect or reconnect it in Settings → Integrations → GitHub; PRs opened after that carry your identity.</Accordion>
  <Accordion title="Commits show 'Capy Agent' as the author">Same cause: your GitHub account is disconnected or needs reauthorization. Until it's reconnected, Capy falls back to its own author identity rather than guessing.</Accordion>
  <Accordion title="A tool that reads GH_TOKEN fails on the machine">Expected: no reusable GitHub token exists on the machine by design. Route the same call through `gh`, which works via Capy's proxy.</Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.