ReaperCI Documentation

ReaperCI documentation

Git provider connections

ReaperCI can adopt repositories from GitHub, Gitea, Forgejo, and GitLab without changing their canonical forge. It creates a native pull mirror for builds, installs a signed push webhook, and reports each build back to the source commit.

Before connecting

  • Set REAPERCI_EXTERNAL_URL to the public HTTPS URL of the ReaperCI hub. Provider webhooks cannot be installed for an HTTP or local-only origin.
  • Create a dedicated, expiring provider token with access only to the repositories ReaperCI should build.
  • Treat provider tokens like passwords. ReaperCI encrypts them with the instance master key and never returns them from list or detail APIs.

Recommended token access:

Provider Base URL Git username Token access
GitHub App https://api.github.com x-access-token Install on selected repositories; Contents read, Pull requests read, Webhooks write, Commit statuses write
GitHub PAT fallback https://api.github.com x-access-token Selected repositories, Contents read, Webhooks write, Commit statuses write
Gitea Your forge origin Token owner Repository read/write and hook/status API access
Forgejo Your forge origin Token owner Repository read/write and hook/status API access
GitLab https://gitlab.com or your origin oauth2 api scope for project discovery, hooks, repository access, and commit statuses

GitHub App installation credentials are recommended for both self-hosted and managed installations. ReaperCI encrypts the App private key, signs a short-lived RS256 App JWT only when needed, exchanges it for a one-hour installation token, and caches that token in memory until its refresh window. Installation tokens are never written to SQLite and their length or prefix is not assumed. A fine-grained or classic PAT remains available as a self-hosted fallback.

Configure a GitHub App

  1. Create a GitHub App owned by the account or organization that will install it.
  2. Grant repository permissions: Contents: read, Pull requests: read, Repository hooks: read and write, and Commit statuses: read and write. Subscribe to push and pull_request events.
  3. Install the App on only the repositories ReaperCI should discover. Record the App ID (or client ID) and installation ID, then generate an RSA private key.
  4. In Repos > Sources, choose GitHub App installation and paste those three values. The private key is encrypted immediately and never returned.
  5. Test the connection. ReaperCI mints an installation token and calls the installation-repository endpoint; a personal /user/repos identity is not required.

Rotate an App private key or PAT from the existing connection card. ReaperCI replaces the encrypted credential atomically, keeps every imported repository attached to the same connection, clears any cached installation token, and marks the connection unverified. Test it before deleting the old key or token in GitHub. GitHub documents the RS256 JWT contract and one-hour installation token exchange.

Connect and import

  1. Open Repos > Sources and save a provider connection.
  2. Test the connection, then choose Discover repos.
  3. Import a repository. ReaperCI clones it into the native Git server and attempts to install a signed push webhook automatically.
  4. Push a commit containing .reaperci.yml. The webhook synchronizes the mirror before the build is queued.

The source card shows ready only after webhook installation succeeds. If the hub was local-only during import, configure its public HTTPS URL and re-import or install the displayed webhook URL manually with the one-time secret.

Commit statuses

For connected repositories, ReaperCI publishes the following lifecycle:

ReaperCI build GitHub / Gitea / Forgejo GitLab
queued pending pending
running pending running
success success success
failed failure failed
canceled error canceled
infrastructure error error failed

Statuses use the reaperci/build context and link to /builds?build=<id>. Delivery is stored separately from the build result, so a provider outage cannot turn valid user code into a failed build. Failed calls use bounded exponential retry and remain visible on the build page. An operator with builds:rw scope can retry a failed status from the dashboard or with:

POST /api/v1/commit-statuses/{id}/retry

Delivery history is available at:

GET /api/v1/builds/{id}/commit-statuses

Troubleshooting

  • 401 or 403 from the provider: rotate the token and verify its repository, webhook, and commit-status permissions.
  • Webhook is pending: confirm the external URL is public HTTPS and that the token can administer repository hooks.
  • Mirror does not update: inspect the signed webhook delivery history on the provider connection, then use Sync on the active mirror.
  • Commit status is failed: open the build, review the recorded provider error, fix credentials or connectivity, and choose Retry.