Documentation

Deploys

A deploy builds what changed and puts it in front of traffic. Some changes can be swapped in; others need the app rebuilt, and the difference is worth knowing before you wonder why a setting did not take.

The sequence

A Git-sourced service is built from its branch, producing an image stamped with the commit it came from. An image-sourced service is pulled. Either way the result is a version recorded in the app's history, and then it goes live.

If a build fails, the app records the reason it failed and keeps the log, so a deploy that did not land is still something you can read rather than something you have to reproduce.

Two ways a deploy lands

These cost you very different amounts of time, which is why they are named rather than both reported as “deployed”:

Swap. The new image replaces the old one and the containers whose image changed restart. Nothing else is touched.
Rebuild. The app is built back up from the beginning. Slower, and necessary for the changes in the table below.

When a change actually takes effect

Saving a setting and that setting being live are not the same moment. This is the table to check when an app is running something you thought you had changed:

What you changed	When it takes effect
Auto-redeploy on push	Immediately. It is read each time a push arrives.
Environment variables, branch, Dockerfile path, image reference	On the next deploy. These are build inputs, so a redeploy picks them up.
Port, exposure, release command	Needs a rebuild. A redeploy is not enough — see below.

Why that last row is not a technicality. The swap path restarts the containers whose image changed and does nothing else: it never re-renders the router configuration, and it skips the release command entirely. So a port, an exposure or a release command changed and then merely redeployed would show you a deploy succeeding while the app carried on with the old setting — a success message for a change that did not happen. Rebuild instead.

Deploying on push

Auto-redeploy is set on the service and fires when you push to its configured branch. Leave it off for an app that should only move when you say so.

Every deploy, automatic or not, becomes a version you can put back. That is on Versions.

When a deploy fails

The app keeps serving whatever was already running — a failed build does not take a working app down. The failure is recorded with the service that caused it, and the build log for that attempt stays available in the history so you can read what happened rather than guess.

The recorded reason is cleared when the app next comes up successfully, so it always describes the current state rather than accumulating a list of every past problem.