Preview environments
Ephemeral, policy-driven environments created per pull request — with optional branched databases — and torn down automatically.
A preview environment is a short-lived deployment spun up for a single pull request so reviewers can click through the change before it merges. Previews are governed by a per-service policy and listed under Deploy → Previews.
Preview policies
A policy binds to a source repository and decides when and how previews are created:
| Field | Meaning |
|---|---|
enabled | Master switch for the policy |
autoCreate | Create a preview automatically when a matching PR opens |
branchPattern | Only create previews for PRs whose branch matches this pattern |
maxConcurrent | Cap on simultaneous previews (oldest are reaped first) |
ttlSeconds | How long an idle preview lives before it auto-expires |
urlTemplate | Template for the public URL, e.g. pr-<N>-<repo>.<owner>.proxifai.app |
baseEnvironmentId | Environment whose manifests the preview overlays |
snapshotDbs | Branch a copy of the base environment’s database for the preview |
authRequired | Put the preview behind authentication |
Manage policies at /api/v1/projects/{projectId}/preview-policies.
Lifecycle
A preview environment moves through these states:
provisioning → running → tearing_down → expired (or failed)
Each preview records the PR it belongs to (number, branch, head SHA, author), its publicUrls, and — when snapshotDbs is on — a sanitized descriptor of its branched database (engine, kind, host; never the password). It carries an expiresAt and is destroyed automatically when the PR closes or the TTL elapses.
Branched databases
When snapshotDbs is enabled, proxifai provisions an ephemeral copy of the base environment’s database for the preview, so reviewers test against realistic data without touching production. These per-PR databases are created and torn down with the preview and appear in Infrastructure → Databases alongside the managed-database catalog (GET /api/v1/preview-databases).
Managing previews
GET /api/v1/projects/{projectId}/preview-environments # list active previews
POST /api/v1/projects/{projectId}/preview-environments/{id}/destroy # tear down now
POST /api/v1/projects/{projectId}/preview-environments/{id}/extend # extend the TTLFrom the UI, the per-PR page links straight to the preview’s URL and shows its status and (if any) branched-database details.