Skip to main content
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

1

Install the GitHub App

Go to 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.
2

Attach repositories to a project

Add the repositories a project should work in. Threads in that project clone them automatically when a machine starts.
3

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.

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

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

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

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.
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.
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.
Attribution follows your connected GitHub account. Connect or reconnect it in Settings → Integrations → GitHub; PRs opened after that carry your identity.
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.
Expected: no reusable GitHub token exists on the machine by design. Route the same call through gh, which works via Capy’s proxy.