Deployment
Deploy, redeploy and roll back
Ship a new release, restart a bad process, cancel a deploy in flight, or go back to a release that worked.
A deployment is one release of one service. It fixes two things the moment it starts: the image that will run, and the configuration it will run with. Because both are fixed, the deploy history of a service is a precise record of what ran — and going back to an earlier release is a matter of picking it.
A service has at most one active deployment. When a new one succeeds, the previous one becomes Replaced and stays in the history.
Where each action lives:
| Surface | Deploy actions |
|---|---|
| Product App | Service → Deployments is the history, one row per release; a deploy still in flight is cancelled from its row, and a build log opens from the deployment it belongs to. Redeploy is on the service panel. Restart service is under Operations on Service → Settings. |
| CLI | Every action on this page: the CLI renders the same operation catalog as MCP. Run it from your own terminal. |
| MCP | Every action on this page. Tool names are linked per section. |
| REST | Every action on this page, under /deployment/…. Browse the endpoints. |
Pick the action
| You want to | Do this | Builds? | New entry in history? |
|---|---|---|---|
| Ship the current source again — after a settings change, an edited variable, or on demand | Redeploy with deployment_service_redeploy | Yes, unless the source is a prebuilt image | Yes |
| Fix a process that has gone bad while the release itself is fine | Restart with deployment_service_restart | No | No |
| Undo a bad release | Roll back with deployment_service_rollback | No — the image is reused | Yes |
| Stop a deploy that is still running | Cancel with deployment_deployment_cancel | — | The cancelled deploy is recorded as failed |
Roll back to a release that worked
- List the service’s deployments, newest first, with
deployment_deployment_list, and pick the release you want back. - Call
deployment_service_rollbackwith that deployment. - Watch it come up. The rollback follows the same path as any other deploy — starting, health check, take-over — but skips the build entirely, so it is much faster.
The target has to be one that actually ran — Active, Replaced or Crashed — and it has to have an image, so a deployment that failed during the build cannot be a rollback target.
A rollback is a new entry in the history, and it records which deployment it was rolled back from. The original stays where it is.
What starts a deploy
- You redeploy the service yourself.
- You push to the branch a repository-backed service tracks. What that does to a service currently at zero replicas depends on its sleep setting — see Scale a service. Static sites always rebuild on a push.
- You push to a pull request that has a preview environment, which redeploys the repository-backed services in that preview.
- You fork an environment, which deploys every copied service that has at least one replica.
- You upload a new build of a prebuilt static site.
How a deploy runs
- Snapshot. The source and the variables are captured onto the deployment. From here on the deploy works from that snapshot.
- Resolve variables. Variables are decrypted where needed and references between them are resolved. A reference that cannot be resolved fails the deploy right here, before any build time is spent.
- Build. For a repository source, your image is built from your
Dockerfile; for a static site, your build command runs and its output is collected. For a prebuilt image, and for a rollback, this step is skipped entirely. The build log streams while it runs, and the build has a deadline of thirty minutes. - Start. The new release starts with the resolved variables and the image from step 3. A static site skips the remaining steps: publishing it is a single switch, and visitors move to the new version in one go.
- Wait until healthy. Lessly waits for the new release to report ready, for up to five minutes. If it never does, the deploy fails and the failure message says what the container was doing when the deadline passed.
- Take over. The new release becomes active and the previous one is marked
Replaced.
Every one of these steps writes to the deploy timeline for the service, so a finished deploy — successful or not — can be read back step by step. See Read logs, events and metrics for build logs, runtime logs and the event history.
Traffic during a rollout
For an ordinary service the new release is started alongside the one already running, and traffic moves over only once the new release reports healthy. Until that moment the previous release is still serving. A deploy that never comes up therefore does not take your service down — it stops, and the version already in production keeps running.
There is one exception. A service with a volume mounted has to release that storage before the new release can claim it, so the running copy is stopped first and there is a short interruption while the new one starts.
Statuses
| Status | Meaning |
|---|---|
Initializing | Accepted; the snapshot is being taken |
Building | Your image or your site is being built |
Deploying | The new release is starting and being checked |
Active | Serving |
Replaced | Superseded by a later deployment |
Crashed | Was active, but its container kept restarting |
Failed | Did not reach the point of serving |
A failed deployment always carries the reason it failed — a missing Dockerfile, a build error, an unresolved variable reference, or a container that never became healthy.
Crashed is not a deploy failure but a runtime one: a release that reached Active and then restarted five times inside five minutes is marked Crashed, so the state is visible without reading logs. Individual restarts are recorded as events before that threshold is reached.
Cancel a deploy in flight
A deploy that is still initializing, building or starting can be cancelled with deployment_deployment_cancel. Any build in progress is stopped, the service is released for a new deploy, and the cancelled deployment is recorded as failed with the reason.
The active deployment cannot be cancelled — it is not in progress — and a deploy that has already finished cannot be cancelled either.
Build history
Every deploy that built something leaves a build record: its status, the commit it built, the resulting image and how long each phase took. Builds are listed newest first per service with deployment_build_list, and a build can be opened on its own with deployment_build_get — useful when you want to compare two builds of the same branch rather than two releases.
Next steps
- Set up a service: change the source, port or health checks a deploy will pick up.
- Work with environments: deploy the same service into
stagingor a pull-request preview. - Connect a domain: redeploying re-applies a service’s routing.
- Read how deployment works: why a release is a snapshot, and what that buys you.