ReaperCI Documentation

ReaperCI documentation

Preview environments

Connected GitHub, Gitea, Forgejo, and GitLab repositories can turn pull or merge requests into isolated Docker preview environments. ReaperCI keeps one durable lifecycle record linking the provider change, build, deployment, URL, and teardown deployment.

Enable previews

Install or refresh the repository webhook after upgrading so it subscribes to pull-request events, then opt the pipeline in:

on:
  pullRequest:
    branches: [main]
    paths: ["src/**", "Dockerfile"]

steps:
  - name: image
    dockerfile: Dockerfile
    tags: [my-app:{{short_sha}}]

deploy:
  target: preview
  previewUrl: https://pr-{{preview_number}}.preview.example.com
  image: my-app:{{short_sha}}
  container: my-app
  approve: auto
  healthCheck:
    url: https://pr-{{preview_number}}.preview.example.com/health

pullRequest.branches filters the provider target branch. paths and pathsIgnore use the same glob behavior as push triggers. Existing pipelines do not begin deploying pull requests unless on.pullRequest is present.

ReaperCI always loads .reaperci.yml from the provider target branch/base SHA, then executes that trusted policy against the pull-request head commit. A pull request therefore cannot change its own target server, approval policy, or deployment command. Preview deployments also receive no environment-scoped secrets unless a future explicit policy grants them.

Preview builds can use these deployment placeholders:

  • {{preview_number}} - provider pull or merge request number;
  • {{preview_environment}} - stable preview-<repo>-<number> name;
  • {{source_branch}} - provider source branch;
  • {{branch_slug}} - lowercase source branch safe for names and host labels.

Run deployments automatically receive a readable -pr-<number>-<stable-id> container suffix even when the pipeline uses a static container name. The stable identifier includes the repository-specific preview environment, which prevents equal PR numbers in different repositories from colliding. Compose deployments run with the preview environment as the Compose project name. Both rules keep concurrent previews isolated on the same VPS.

Lifecycle and teardown

Opening, reopening, or synchronizing a provider change quietly refreshes the mirror and queues one pull_request build. The preview moves through queued, building, ready, deploying, and active; skipped filters and failures are retained with a recovery message.

Closing or merging the provider change cancels queued/running work and queues a typed deploy.teardown operation for active runtimes. Direct SSH uses a bounded docker rm -f or docker compose ... down --remove-orphans command. The outbound connector accepts the same structured operation and never receives an unrestricted shell command.

If a close arrives while deployment is already running, the preview stays in closing and teardown is queued immediately after that deployment finishes. Manual close and retry controls are available in Previews.

Automation

reaperci previews list --repo my-app
reaperci previews get 12
reaperci previews retry 12
reaperci previews close 12
  • REST: /api/v1/preview-environments
  • MCP: reaperci_previews_list, reaperci_preview_get, reaperci_preview_retry, and destructive reaperci_preview_close

Every manual retry or close is attributed to the user or service account and recorded in the append-only audit log. Provider credentials and environment secret values are never returned by preview APIs.