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)
Deployment lifecycle (state)
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
- Startup —
startPreviewDecayScheduler()registers a leader-only job: with several API replicas only the holder of theplatform-api-leaderLease runs it (see Background jobs) - Interval — Every 15 minutes, the scheduler queries for stale preview deployments:
environment_idmatches a preview environment- Status is
deployed,building, ordeploying created_atis older than 72 hourspreview_urlis not null
- Cleanup — For each expired deployment:
terminateK8sPreview(branch)— removes K8s resources- Status set to
expired terminatedAttimestamp 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.