# Deploy, redeploy and roll back

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](/interfaces/cli). |
| MCP | Every action on this page. Tool names are linked per section. |
| REST | Every action on this page, under `/deployment/…`. [Browse the endpoints](/reference/openapi/deployment). |

## 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`](/reference/mcp-tools/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`](/reference/mcp-tools/deployment_service_restart) | No | No |
| Undo a bad release | **Roll back** with [`deployment_service_rollback`](/reference/mcp-tools/deployment_service_rollback) | No — the image is reused | Yes |
| Stop a deploy that is still running | **Cancel** with [`deployment_deployment_cancel`](/reference/mcp-tools/deployment_deployment_cancel) | — | The cancelled deploy is recorded as failed |

> **WARNING**
> Only one deploy per service can be in flight at a time. Starting a second while the first is still running is refused rather than queued — cancel the running one first if you want to replace it.

## Roll back to a release that worked

1. List the service's deployments, newest first, with [`deployment_deployment_list`](/reference/mcp-tools/deployment_deployment_list), and pick the release you want back.
2. Call [`deployment_service_rollback`](/reference/mcp-tools/deployment_service_rollback) with that deployment.
3. 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.

> **WARNING**
> A rollback restores the image, not the configuration. It runs with the variables as they are today, not with the values that were in place when the target release was first deployed. If you rolled back to undo a variable change, change the variable back as well.

## 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](/ship/deployment/scaling). 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](/ship/deployment/environments), 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

1. **Snapshot.** The source and the variables are captured onto the deployment. From here on the deploy works from that snapshot.
2. **Resolve [variables](/ship/deployment/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.
3. **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.
4. **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.
5. **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.
6. **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](/ship/deployment/observability) 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](/ship/deployment/data) 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`](/reference/mcp-tools/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`](/reference/mcp-tools/deployment_build_list), and a build can be opened on its own with [`deployment_build_get`](/reference/mcp-tools/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](/ship/deployment/services): change the source, port or health checks a deploy will pick up.
- [Work with environments](/ship/deployment/environments): deploy the same service into `staging` or a pull-request preview.
- [Connect a domain](/ship/deployment/domains): redeploying re-applies a service's routing.
- [Read how deployment works](/ship/deployment): why a release is a snapshot, and what that buys you.