Rollback and Promote Deployments on Launchverse: The Operator's Playbook

Every production system breaks eventually. The question is how long it takes you to recover. This guide walks through the three Launchverse primitives for getting back to a known-good deployment — rollback, promote, and auto-rollback — when each one is the right tool, what they cost, and the configuration that makes auto-rollback do its job without false positives.

Three primitives, three different jobs

They share an engine path under the hood: all three re-pin the production application's git_commit_sha and trigger a fresh build. The difference is who fires them and against which commit.

Rollback — operator-driven, commit-targeted

To roll back manually, open the Deployments tab on a project, find the last green deploy you trust, and hit Rollback. We:

1. Refresh the engine's tokenized clone URL (private repos drift after ~60 minutes; this avoids could not read Username for github.com mid-rollback).
2. PATCH the production application's git_commit_sha to the target commit.
3. POST /applications/{uuid}/restart to rebuild + re-deploy at that commit.
4. Write a new Deployments row with commit_message = "Rollback to <abbrev>" so the timeline stays honest.
5. Stream the rollback's progress on the same SSE feed you'd see for a push deploy — status pill, log lines, email-on-finish, working Cancel button.

Rollbacks bill build minutes like any other deploy, but they go through the admission gate with skipBuildMinutes set when you're inside the build-minute cooldown — i.e. you cannot pile up 5 simultaneous rollbacks that all charge a Pro team's monthly minute quota. The concurrency cap still applies.

If you need to roll back to a commit that isn't in the Deployments list (e.g. a commit that never reached production), push that commit to your trigger branch and let the normal push-deploy path handle it — that's faster than manually pinning a commit that the engine has never seen.

Promote — flip a preview commit into production

When PR Previews are enabled on a project, each preview's row in the Previews tab has a Promote to production button. Hitting it:

1. Looks up the commit SHA the preview was last built against.
2. Re-deploys the project's main production application pinned to that commit — not the preview's commit ref, the actual SHA. This means a force-push to the preview branch after promotion will not silently change what's in production.
3. Streams the promotion on the same SSE feed as a push deploy. Cancel, status, email-on-finish all work.
4. Leaves the preview environment open. The preview is independent of production from this moment on — closing the PR still tears down the preview without touching the production deploy you just made.

Promote is the right primitive for "this PR is signed-off; I want to ship it without merging it to main first". It is not the right primitive for routine git-flow shipping — for that, merge the PR and let auto-deploy on push do its job. Promote skips the audit trail of a real git merge.

Auto-rollback — health-probe-driven

After every successful deploy, Launchverse runs a post-deploy HTTP health probe against your live URL for 60 seconds. If three or more samples return HTTP ≥ 500 (or timeout) inside that window, we automatically:

1. Mark the just-shipped deploy as auto-rolled-back.
2. Re-deploy the previous green commit.
3. Fan out a notification + a deploy-failed email with the diagnostic data.
4. Post a Failed commit status back to GitHub on the offending SHA.
5. Stamp a 30-minute cooldown on the project so a chain reaction (previous green also turns out to be broken) cannot rollback-loop you.

Configuring the probe

Three knobs on every project's Settings page, under the Deploy / Reliability section:

• auto_rollback_enabled — On by default. Turn it off if your API legitimately returns 5xx on its health URL (some legacy systems return 503 during slow boot).
• health_probe_path — Defaults to /. Set it to something like /healthz or /health so the probe checks a real liveness endpoint instead of your homepage. The probe appends this path to your live URL and follows redirects.
• last_auto_rollback_at — Stamped automatically when auto-rollback fires. Used internally to enforce the 30-minute cooldown.

What a good health endpoint looks like

// /healthz — Express
app.get("/healthz", async (_req, res) => {
  try {
    await db.raw("SELECT 1");      // can we reach the DB?
    await redis.ping();            // can we reach Redis?
    res.status(200).send("ok");
  } catch {
    res.status(503).send("unhealthy");
  }
});

Two things to notice:

1. The endpoint actively checks the dependencies the app needs to serve real traffic. Returning 200 from a static handler is worse than not having a healthcheck at all — it tells auto-rollback that an app with an unreachable database is healthy.
2. The endpoint returns 503 (not 500, not 502) when something's wrong. 503 is "I know I'm broken and the platform should not route to me yet", which is exactly what you want auto-rollback to notice.

When auto-rollback won't fire

Auto-rollback respects three opt-outs:

• The project's owner has flipped auto_rollback_enabled to false.
• The 30-minute cooldown is active (the most recent auto-rollback fired less than 30 minutes ago).
• There's no previous green commit to roll back to. First deploys don't get an auto-rollback target.

When any of these short-circuits the probe, you still get the deploy-failed email — auto-rollback is a recovery tool, not a notifier, and the platform's other observability paths (build-finished email, GitHub commit status, Slack webhook if configured) fire regardless.

What it costs

The rationale for auto-rollback being free: the platform fired it, not you. Charging build minutes for the platform's own incident response would create the wrong incentives.

When to reach for each

A pragmatic decision tree:

• A bad commit shipped and the live URL is still passing healthchecks → Rollback to the last known-good commit.
• A bad commit shipped and the live URL is hot-on-fire 5xx → auto-rollback will fire within a minute; if it doesn't, Rollback manually and check whether your health probe is configured.
• A preview build looks good and you want it live without merging → Promote.
• A preview build looks good and you can merge cleanly → merge the PR, let auto-deploy on push handle it. Cleaner audit trail.

Related guides

• Zero-downtime deployments — how the platform handles the deploy itself, including the graceful-shutdown step that lets a rollback finish without dropping in-flight requests.
• PR preview deployments — how preview environments work, what's isolated from production, how to use the commit you tested in promotion.
• Production observability without Datadog — how to read the deploy-success-rate, build-minute, and reliability metrics your project surfaces, including the deploy-history that auto-rollback writes to.