Rolling Back a Deployment

If a deployment breaks production, you can put an earlier build back in front of traffic in seconds without rebuilding anything. This guide covers how rollback works, how to pick the right deployment, the automatic rollbacks Orbit can perform for you, and what to do after you have rolled back.

How Rollback Works

Orbit keeps the packaged artifact of every successful build. A rollback does not re-run your install or your build command: it promotes an artifact that already exists and has already been served, so it completes in seconds and cannot fail for any of the reasons a build can fail.

That is the whole reason to reach for it first. Rolling back is faster, and far more predictable, than trying to fix forward while your site is broken.

Rolling Back To a Previous Deployment

Open your project in Orbit.
Open the Deployments tab.
Find the last deployment you know was good.
Click Roll back on that row and confirm.

The confirmation says exactly what will happen: traffic will be served from the older build immediately, and the current deployment will be superseded.

Deployments tab with the roll back action

You can also roll back from a deployment's own detail page, where the button reads Rollback to the short commit hash.

The restored deployment picks up the CURRENT badge. The deployment you rolled away from stays in the history with the status Rolled back.

Rollback is not destructive and does not need undoing. Nothing is deleted, no history is rewritten, and your repository is untouched. Your next successful push to the production branch simply becomes the new live version in the normal way.

Identifying the Right Deployment

Each row on the Deployments tab shows the commit message and short hash, the branch, the status, when it deployed, and who pushed it. The live one carries the CURRENT badge.

Usually you want the deployment immediately before the one that caused the problem. Two things help you be sure:

Compare. Open the suspect deployment and click Compare to diff it against the previous one: build time, artifact size, cache state, framework, and the file-level artifact difference.
Deployment notes. Any deployment can carry a note of up to 500 characters. Adding "hotfix for payment bug" or "feature flag X on" at the time costs nothing and makes the history readable months later, which is exactly when you need it.

Rolling back to an artifact does not roll back your environment variables, redirect rules or response headers. Those are read at the time of the request or the build, not baked into the artifact. If the incident was caused by a configuration change rather than a code change, rolling back the code will not fix it. The deployment detail page diffs the variables that were injected at build time against your current configuration, which is the quickest way to tell the two apart.

Automatic Rollback

Orbit can do this for you before you have even noticed. All three settings are in Settings.

Auto-Rollback On Failure

Under Runtime, turn on Auto-rollback on failure. If a production deploy fails, the last healthy deployment is restored automatically and visitors see no downtime. Staging has an equivalent toggle of its own.

Health Check

Under Health check, set a Health check path, for example / or /api/health. After every production deploy, Orbit fetches that path. If it does not return a 2xx response within 15 seconds, the previous healthy deployment is restored.

Smoke Tests

Under Smoke tests, list up to 10 comma-separated paths, for example /,/blog,/api/health. After each successful deploy, Orbit sends a GET to each and records pass or fail. If any fail and auto-rollback is enabled, the previous deployment is restored. The result appears on the deployment page as Smoke tests passed or a failure count, and says Triggered rollback when it caused one.

A health check on a route that actually exercises your database is worth far more than one on the home page. A broken deploy that still serves a cached home page will pass a / check and fail a real one.

Rollback Versus Deploy Lock

If you are not ready to roll back but want to stop anything new going live while you investigate, lock deploys instead:

Open the project.
Click Lock deploys.
Add a reason, for example "investigating production issue".

Push-triggered deployments are then silently skipped, and a banner reads Production deploys are locked with your reason. Manual deploys still work, which is deliberate: the lock stops accidental deploys, not the fix you are shipping. Click Unlock deploys to lift it.

A lock and a rollback work well together. Roll back first to restore service, then lock so nobody's routine merge undoes it while you are diagnosing.

Promoting Staging To Production

If you run a staging environment, you can put a tested staging build into production without pushing anything.

Open the project overview and find the Staging section.
If staging is ahead of production, Promote to production appears.
Click it and confirm.

Read the confirmation carefully, because there are two different promotion behaviours in Orbit and they are not interchangeable. Promoting from the project overview triggers a fresh production build at the same commit, using production environment variables and production build commands. The staging artifact is not reused. Promoting a specific staging deployment from its detail page states plainly that the staging build goes live immediately without a rebuild. If your staging and production environment variables differ, the first path will produce a different artifact from the one you tested.

Orbit can also promote for you. Auto-promote staging in Settings promotes staging to production after a number of hours of healthy staging with smoke tests passing, checked every 15 minutes.

After a Rollback

Fix the underlying problem in your repository and push a new commit. That triggers a normal build which becomes the new live version. If you locked deploys, unlock them first, or the push will be skipped.

The project Activity tab records the rollback along with everything else that happened, so there is an audit trail of who rolled back what and when.

What Limits How Far Back You Can Go

Rollback needs the artifact to still exist. Two settings control that:

Your plan's deployment history window: 7 days on Launch, 30 on Liftoff, 90 on Apex.
The project's Artifact retention setting, which keeps a number of successful artifacts per environment, from 10 to 500, defaulting to 50.

The currently live deployment's artifact is always kept regardless of either.

If you deploy many times a day, the artifact count is the limit you will hit first, not the day count. Fifty deploys can be a single week. Raise Artifact retention rather than discovering the ceiling during an incident.