Ci Ephemeral Previews

Ephemeral Pull Request Previews & Automatic Teardown

1. Executive Summary & Objectives

Deploying cloud preview workers on every Pull Request commit across a multi-tenant monorepo would consume excessive GitHub Actions runner minutes and leave orphaned preview workers in Cloudflare.

SiteSwarm’s ephemeral preview lifecycle enforces two principles:

Opt-In Ephemeral Provisioning: Cloud preview deployments run only when explicitly requested on a Pull Request (preview-deploy label or manual workflow dispatch).
Automatic Teardown (Zero Orphans): Closing or merging a Pull Request automatically decommissions its ephemeral preview workers so temporary preview infrastructure never lingers in the Cloudflare account.

flowchart LR
    Trigger["PR Opt-In Trigger\n('preview-deploy' Label or Dispatch)"] --> Deploy["Deploy Preview Worker\n(<app>-preview-pr-<N>)"]
    Deploy --> Health["Edge Health Probe &\nIdempotent PR Comment (Links + QR)"]
    Health --> Close["PR Closed or Merged"]
    Close --> Teardown["Delete Preview Worker &\nMark Comment Decommissioned"]

2. Preview Provisioning & Idempotent PR Feedback

Deterministic Preview Naming: When preview-deploy is applied to Pull Request #<N>, the preview workflow deploys impacted client applications (determined by CI_CHANGE_DETECTION.md) using the deterministic worker name <app>-preview-pr-<N> under the preview URL convention defined in CI_DEPLOYMENT_ENVIRONMENTS.md.
Edge Readiness Verification: After deployment, CI probes the live edge preview URL to verify that the Worker isolate boots and responds with HTTP 200 OK.
Single Idempotent PR Comment: Rather than spamming a new comment on every commit push, the workflow maintains a single sticky Pull Request comment containing the live preview URLs, commit SHA, and scannable mobile QR codes for instant device testing.

3. Automatic Teardown Lifecycle

Close / Merge Hook: When a Pull Request is closed or merged, the preview cleanup workflow executes automatically.
Cloud Resource Deletion: The cleanup job deletes the <app>-preview-pr-<N> Cloudflare Worker scripts associated with that PR and updates the sticky PR comment to indicate that the preview environment has been decommissioned.