Connect a GitHub repository

Keep GitHub canonical while ReaperCI owns build, registry, deployment, and live operations.

1. Set REAPERCI_EXTERNAL_URL to the public HTTPS hub URL.
2. Create a GitHub App with Contents read, Pull requests read, Repository hooks write, and Commit statuses write. Install it on only the selected repositories.
3. In Repos > Sources, choose GitHub App installation, then enter https://api.github.com, the App or client ID, installation ID, and generated RSA private key. Use a fine-grained PAT only as a self-hosted fallback.
4. Test the connection, discover repositories, and import one. The card becomes ready after the pull mirror and signed webhook are installed.
5. Add .reaperci.yml on a branch and open a pull request. Confirm that ReaperCI uses the default-branch pipeline policy, creates a preview when configured, and posts the reaperci/build status.
6. Merge and verify that the signed webhook synchronizes the mirror before the push build starts.

If webhook installation fails, confirm the hub is public HTTPS and the App has repository-hook permission on that selected repository. Reinstall or rotate the App credential rather than broadening a personal token indefinitely. Provider status delivery failures remain separate from the user build result and can be retried from the build page.

Use Rotate credential on the existing connection when GitHub issues a new private key or token. Repository mirrors remain attached, but the connection is marked unverified until its next successful test.

For permissions and status mapping, see Git provider connections.