Branch Preview Environments

MicroFly provides ephemeral preview environments, allowing developers and QA teams to deploy and test pull requests or feature branches in isolated environments with dedicated URLs before merging to production.

---

1. Deploying a Preview Environment

You can deploy a branch preview either via the CLI or by pushing a feature branch over Git:

Via the CLI

sudo microfly deploy --dir . --branch feature/checkout --ttl 24h my-app

Via Git Push

git push production feature/checkout

---

2. Automated Domain Derivation

MicroFly synthesizes a unique, deterministic preview name and host route for every branch:

• Preview App Name: <base-app>-<branch-slug>-<short-hash> (e.g. my-app-feature-checkout-df7c7aeb)
• Preview Domain: Injected as a subdomain prefix into all configured domains:
  • Base domain: api.example.com
  • Preview domain: feature-checkout-df7c7aeb-api.example.com
  • Wildcard base domain: *.internal.net
  • Preview domain: feature-checkout-df7c7aeb.internal.net

All wildcard routing configured in your reverse proxy (e.g. *.example.com) routes to the preview without manual web server reconfiguration.

---

3. Listing Active Previews

To inspect all active preview environments, their base applications, and remaining time-to-live:

sudo microfly preview list

Output:

PREVIEW                           BASE APP   STATUS   RELEASE                 EXPIRES IN  DOMAINS
my-app-feature-checkout-df7c7aeb  my-app     stopped  20260903T101530-000001  23h58m      feature-checkout-df7c7aeb-api.example.com

---

4. Promoting a Preview to Production

Once a feature is reviewed and approved, you can instantly promote the preview release to your primary production application without rebuilding or pushing code:

sudo microfly preview promote my-app-feature-checkout-df7c7aeb

Output:

promoted preview my-app-feature-checkout-df7c7aeb to release 20260903T102000.123456789Z-000003

The production application atomically shifts its ingress traffic to the tested release, while preserving production secrets, environment variables, and persistent volumes.

---

5. Expiration & Automatic Sweeping

Every preview environment has a Time-To-Live (TTL), configured either in app.toml under [preview] ttl = "48h" or via the --ttl deployment flag.

• Previews persist their expiry timestamps on disk in preview.json.
• The MicroFly daemon periodically checks for expired previews and safely destroys their releases, transient units, and routes.
• You can also manually trigger a sweep at any time:

  sudo microfly preview sweep

To immediately tear down a preview before its TTL expires:

sudo microfly apps destroy my-app-feature-checkout-df7c7aeb