Skip to Content
Slloy Docs
Operations, Deployment & DR

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

DimensionStaging (slloy-staging-api)Feature (slloy-feature-<slug>-<hash>)
URL & Accesshttps://staging.slloy.com (behind Cloudflare Access)https://<name>.zsg8482.workers.dev (publicly reachable; do not share externally)
APP_ENVstagingfeature (decoupled from NODE_ENV=production)
Custom Routes & CronBound to staging.slloy.com; runs */5 and 0 * CronsNone (disables Cron to prevent duplicate sweeping and settlement against staging)
Image Queue (IMAGE_QUEUE)Producer + ConsumerProducer Only (queue consumption is handled by slloy-staging-api)
Neon DB & R2 Bucketslloy_staging / slloy-staging-uploadsShared 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 loglog (RESEND_API_KEY is not injected by default)

2. How to Deploy or Delete a Feature Environment

On any open Pull Request (from a repository Owner, Member, or Collaborator—fork PRs are ignored for security):

  • Deploy / Update: Comment /feature-env on the PR timeline.
    • The workflow adds the feature-env label to the PR, builds the branch, deploys the Worker, posts a comment with the live .workers.dev URL, and creates a GitHub feature-<slug> deployment entry (View deployment).
  • Delete Immediately: Comment /feature-env delete on 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 be main)
  • operation: deploy or delete

3. Automated Teardown & TTL Garbage Collection

  1. On PR Close / Merge (Feature Environment Cleanup):
    • When any PR carrying the feature-env label is closed or merged, the cleanup workflow automatically deletes that branch's Cloudflare Worker. (Do not manually remove the feature-env label before closing the PR).
  2. Daily TTL & Capacity Cap (03:17 Daily Cron):
    • Deletes any feature Worker that has not been updated in > 14 days 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 most 5 remain.
    • Feature environments attached to an open PR are never deleted by the daily TTL sweep.

4. Build & Config Derivation (tools/feature-env.ts)

  1. Checks out the target branch and runs npm ci && npm run build:web && npm run build:worker.
  2. Runs fast asset gates (npm run check:wrangler -- --expect-target staging and npm run check:assets).
  3. node tools/feature-env.ts config --branch <branch> derives .worker-dist/ssr/feature.wrangler.json from .worker-dist/ssr/wrangler.json:
    • Rewrites name to slloy-feature-<slug>-<hash>, sets workers_dev: true and APP_ENV: "feature", strips routes, triggers, and queues.consumers, and asserts the database target is slloy_staging.
  4. Deploys via npx wrangler deploy -c .worker-dist/ssr/feature.wrangler.json, generates/reuses persistent ADMIN_JWT_SECRET and BETTER_AUTH_SECRET secrets on that Worker, and smoke-tests /api/health (ok=true) and /prompts.

On this page