Feature Environments (Per-Branch Preview Workers)
Ephemeral per-branch Cloudflare Workers (<name>.zsg8482.workers.dev), PR /feature-env slash commands, shared staging DB/R2 architecture, and automated TTL cleanup.
Feature Environments allow any non-main branch to be deployed as an isolated Cloudflare Worker (slloy-feature-<slug>-<hash>.zsg8482.workers.dev) so multiple branches can be tested in parallel without overwriting staging.slloy.com.
1. Staging vs. Feature Environment Comparison
| Dimension | Staging (slloy-staging-api) | Feature (slloy-feature-<slug>-<hash>) |
|---|---|---|
| URL & Access | https://staging.slloy.com (behind Cloudflare Access) | https://<name>.zsg8482.workers.dev (publicly reachable; do not share externally) |
APP_ENV | staging | feature (decoupled from NODE_ENV=production) |
| Custom Routes & Cron | Bound to staging.slloy.com; runs */5 and 0 * Crons | None (disables Cron to prevent duplicate sweeping and settlement against staging) |
Image Queue (IMAGE_QUEUE) | Producer + Consumer | Producer Only (queue consumption is handled by slloy-staging-api) |
| Neon DB & R2 Bucket | slloy_staging / slloy-staging-uploads | Shared with Staging (zero new DB/R2 provisioning or migrations required) |
Payments (PAYMENTS_ENABLED) | Controlled by vars (default false) | Forced false |
Mail Provider (MAIL_PROVIDER) | resend (optional) or log | log (RESEND_API_KEY is not injected by default) |
2. How to Deploy or Delete a Feature Environment
Method A: PR Comment Slash Command (Recommended)
On any open Pull Request (from a repository Owner, Member, or Collaborator—fork PRs are ignored for security):
- Deploy / Update: Comment
/feature-envon the PR timeline.- The workflow adds the
feature-envlabel to the PR, builds the branch, deploys the Worker, posts a comment with the live.workers.devURL, and creates a GitHubfeature-<slug>deployment entry (View deployment).
- The workflow adds the
- Delete Immediately: Comment
/feature-env deleteon the PR.
Method B: Manual GitHub Actions Trigger (For Branches Without a PR)
Go to Actions -> Feature Environment -> Run workflow:
- Use workflow from:
main ref: Target branch name (cannot bemain)operation:deployordelete
3. Automated Teardown & TTL Garbage Collection
- On PR Close / Merge (
Feature Environment Cleanup):- When any PR carrying the
feature-envlabel is closed or merged, the cleanup workflow automatically deletes that branch's Cloudflare Worker. (Do not manually remove thefeature-envlabel before closing the PR).
- When any PR carrying the
- Daily TTL & Capacity Cap (
03:17Daily Cron):- Deletes any feature Worker that has not been updated in
> 14days and has no open PR. - If the total number of active feature Workers without an open PR exceeds
5, deletes the oldest unoccupied environments until at most5remain. - Feature environments attached to an open PR are never deleted by the daily TTL sweep.
- Deletes any feature Worker that has not been updated in
4. Build & Config Derivation (tools/feature-env.ts)
- Checks out the target branch and runs
npm ci && npm run build:web && npm run build:worker. - Runs fast asset gates (
npm run check:wrangler -- --expect-target stagingandnpm run check:assets). node tools/feature-env.ts config --branch <branch>derives.worker-dist/ssr/feature.wrangler.jsonfrom.worker-dist/ssr/wrangler.json:- Rewrites
nametoslloy-feature-<slug>-<hash>, setsworkers_dev: trueandAPP_ENV: "feature", stripsroutes,triggers, andqueues.consumers, and asserts the database target isslloy_staging.
- Rewrites
- Deploys via
npx wrangler deploy -c .worker-dist/ssr/feature.wrangler.json, generates/reuses persistentADMIN_JWT_SECRETandBETTER_AUTH_SECRETsecrets on that Worker, and smoke-tests/api/health(ok=true) and/prompts.
Staging Environment & Local Development
Staging Cloudflare Worker architecture, build order (build:web -> build:worker), Cloudflare Access Service Token smoke verification, Stripe sandbox, and QA tools.
Backup, Rollback & Disaster Recovery Runbook
Recovery runbooks for Cloudflare Worker code rollbacks, append-only R2 media backups (rclone copy), quarterly Neon 7-day PITR drills, and DLQ inspection.