Preview Environments

Preview environments are ephemeral deployments created automatically on every Git push to a non-main branch. They provide a full-stack preview URL with an isolated Kubernetes namespace, enabling developers and reviewers to test changes before merging.


Deployment Pipeline

Push → preview URL (sequence)

sequenceDiagram autonumber actor Dev as Developer participant Git as Git host participant API as Cairn API participant K8s as k3s cluster participant CU as ClickUp / SMTP Dev->>Git: push branch<br/>(non-main) Git->>API: POST /api/webhooks/{github|gitlab}<br/>signed payload API->>API: match repo → Project<br/>generate preview URL<br/>insert Deployment (BUILDING) API->>K8s: deployK8sPreview(project, branch, tag) K8s-->>API: namespace + deployment + service + ingress created API->>API: Deployment → DEPLOYED,<br/>previewUrl populated API->>CU: post preview comment / email API-->>Dev: preview URL ready

Deployment lifecycle (state)

stateDiagram-v2 [*] --> BUILDING: webhook received BUILDING --> DEPLOYING: image pushed DEPLOYING --> DEPLOYED: pods Ready DEPLOYING --> FAILED: rollout failed DEPLOYED --> EXPIRED: 72 h TTL reached DEPLOYED --> TERMINATED: PR closed / manual terminate FAILED --> [*] EXPIRED --> [*] TERMINATED --> [*]

Webhook Events

Event Action Result
push (non-main branch) Preview created/updated New preview deployment
push (main/master) Staging deployment triggered GitLab pipeline + ArgoCD sync
pull_request opened/synchronized Preview created/updated Preview + ClickUp comment
pull_request closed (not merged) Preview terminated K8s resources cleaned up
merge_request open/update (GitLab) Preview created/updated Preview + ClickUp comment
merge_request close/merge (GitLab) Preview terminated K8s resources cleaned up

Preview URL Format

Preview URLs follow the pattern:

https://{project-slug}-{sanitized-branch}.preview.{DOMAIN}
// platform/api/src/lib/preview.ts
export function generatePreviewUrl(branch, projectSlug, suffix) {
  const sanitized = branch
    .replace(/^(feature|fix|chore)\//i, '')
    .replace(/[^a-zA-Z0-9-]/g, '-')
    .toLowerCase();
  return `${projectSlug}-${sanitized}.preview.${suffix}`;
}

Examples

Branch Project Preview URL
feature/CU-842-auth-fix my-app https://my-app-cu-842-auth-fix.preview.platform.example.com
fix/CU-123-upload-timeout dashboard https://dashboard-cu-123-upload-timeout.preview.platform.example.com
chore/deps-update api-gateway https://api-gateway-deps-update.preview.platform.example.com

PR/MR Number Format

When triggered from a pull/merge request, metadata includes the PR/MR number:

https://{project-slug}-{sanitized-branch}.preview.{DOMAIN}

72-Hour TTL with PreviewDecayScheduler

Preview environments have a maximum lifetime of 72 hours. The PreviewDecayScheduler automatically cleans up expired environments.

How It Works

// platform/api/src/lib/preview-decay.ts
const PREVIEW_TTL_MS = 72 * 60 * 60 * 1000;    // 72 hours
const CHECK_INTERVAL_MS = 15 * 60 * 1000;       // Check every 15 minutes
  1. Startup — startPreviewDecayScheduler() registers a leader-only job: with several API replicas only the holder of the platform-api-leader Lease runs it (see Background jobs)
  2. Interval — Every 15 minutes, the scheduler queries for stale preview deployments:
    • environment_id matches a preview environment
    • Status is deployed, building, or deploying
    • created_at is older than 72 hours
    • preview_url is not null
  3. Cleanup — For each expired deployment:
    • terminateK8sPreview(branch) — removes K8s resources
    • Status set to expired
    • terminatedAt timestamp recorded
    • Metadata includes decayReason: "72h-ttl-expired"
# logs
[decay] Preview decay scheduled on the leader (TTL: 72h, check: 900s)
[decay] run started (platform-api-7c9f-abcde)
[decay] Found 3 expired preview deployments
[decay] Expired preview: feature/CU-842-auth-fix (uuid)

Configuration

Parameter Environment variable Default
TTL PREVIEW_TTL_HOURS 72 hours
Check interval PREVIEW_DECAY_INTERVAL_SECONDS 900 (15 minutes)
Initial delay after gaining leadership — 30 seconds (or the interval, if shorter)

Environment Variables Per Preview

Each preview environment inherits the project's environment variables from the ProjectConfig and Secret entities, scoped to the preview environment.

Variables can be set per-preview by creating secrets with the preview environment's UUID:

POST /api/projects/:projectId/secrets
{
  "key": "FEATURE_FLAG_NEW_UI",
  "value": "true",
  "environmentId": "<preview-environment-uuid>"
}

Preview-specific config values can also be set:

POST /api/config
{
  "projectId": "...",
  "key": "LOG_LEVEL",
  "value": "debug",
  "environmentId": "<preview-environment-uuid>"
}

SDK Injection in Previews

When a service runs in preview mode with the Cairn SDK, the config endpoint automatically resolves the correct environment and injects the appropriate secrets:

GET /api/sdk/config?projectId=<projectId>&environmentId=<preview-env-id>

Manual Cleanup

POST /api/deployments/:id/terminate
Authorization: Bearer <token>

This sets the deployment status to TERMINATED. K8s preview resources are cleaned up via the webhook flow when a PR/MR is closed.