ReaperCI Documentation

ReaperCI documentation

Migration and adoption guide

ReaperCI does not require a Git-provider migration. The lowest-risk adoption path is to keep GitHub, Gitea, Forgejo, or GitLab canonical, connect it as a source, prove CI and a staging deployment, and move production only after the rollback drill succeeds. Native ReaperCI Git is available for teams that want a single self-hosted endpoint.

Before changing delivery

  1. Install ReaperCI on supported Linux infrastructure and set its public HTTPS URL.
  2. Back up the existing forge, registry, CI configuration, deployment manifests, secrets inventory, and production rollback procedure.
  3. Create a dedicated staging server and least-privilege deployment account.
  4. Define development, staging, and production environments. Protect production and require human approval.
  5. Inventory secrets by name and destination. Re-enter them in ReaperCI; never copy secret values into .reaperci.yml or migration notes.

Adopt an existing provider repository

  1. Open Repos > Sources and create the provider connection described in Git provider connections.
  2. Discover and import one non-critical repository. ReaperCI creates a native pull mirror while the provider stays canonical.
  3. Add .reaperci.yml on a migration branch. Start with tests only and enable manual runs.
  4. Open a provider pull request. Confirm the trusted-base preview policy, provider commit status, build logs, artifacts, and teardown behavior.
  5. Merge to the default branch and confirm webhook synchronization before disabling the old CI job.
  6. Add the staging deployment, health check, and manual approval. Run and roll back one release before adding production.
  7. Keep the previous delivery path available until ReaperCI has completed at least two normal production release cycles and a restore drill.

Provider import is resumable: a failed clone or webhook does not change the canonical repository. Fix credentials or public URL, retry synchronization, and inspect the signed delivery history before switching CI.

Move a repository to native ReaperCI Git

Create an empty native repository, then mirror all refs from a reviewed clone:

git clone --mirror https://old-forge.example/team/app.git app.git
cd app.git
git remote add reaperci https://ci.example.com/git/app.git
git push --mirror reaperci

Verify branches, tags, default branch, commit count, and a clean clone from both HTTP and SSH. Update developer remotes only after verification. Keep the old repository read-only for the agreed retention period; do not delete it as part of the cutover.

Convert an existing pipeline

Map each old job to a small, explicit ReaperCI step. Use dependsOn for ordering, timeout for every external integration, platform for architecture-specific work, and resources for untrusted or expensive steps. Cache package-manager directories, retain only useful artifacts, and keep deployment policy in the trusted default branch.

Do not put a deploy command inside a normal run step. Use the top-level deploy: block so environment policy, approvals, health checks, audit, drift, promotion, and rollback remain enforceable.

Upgrade an existing ReaperCI installation

Current routes under /api remain compatibility aliases through at least v1.1; new clients should use /api/v1. Existing administrator, tokens, repositories, builds, deployments, secrets, and servers migrate in place. Existing pipeline files keep their behavior.

Before each upgrade:

  1. Record the current image tag and version.
  2. Create a complete data backup and separately verify the matching master key.
  3. Run the upgrade tool with an immutable image tag.
  4. Verify health, login, repositories, one native/provider clone, registry pull, build history, connector state, and a non-production deployment.
  5. If application health fails, let the tool restore the previous image. If a forward-only schema change must be undone, restore the matching pre-upgrade data backup and key rather than starting an older binary on newer state.

Exit and portability

A self-hosted export is the complete ReaperCI data volume plus the separately retained master key and operator configuration. It contains SQLite state, native bare repositories, registry blobs, artifacts, SSH host state, and generated credentials. Provider-connected repositories remain available at their source.

Test the exit path on an isolated host: restore, clone every native repository, pull representative images, download retained artifacts, and compare repository refs and registry digests. ReaperCI Cloud is not required to perform or approve this recovery.