# Deployments & rollback

Every [deploy](/docs/apps/deploy-a-container) creates a deployment: a numbered, immutable version of one service. This page covers what a deployment records, the statuses it moves through, the live timeline of a running deploy, and how to roll back to a prior version.

## Deployments are immutable

A deployment records everything Koo needs to reproduce that release:

- 
- 
- 
-

Nothing ever edits a shipped version. Changing a service's image or configuration creates the next version; existing versions stay exactly as they shipped. That permanent history is what makes rollback safe — there is always a known-good release to return to.

The full object shape is documented in the [API reference](/api/objects/deployment).

## Deployment statuses

> **Note:**
>
> `applied` is a pipeline verdict, not a health verdict. It means the new version was accepted; whether the new code boots and becomes ready is runtime truth, shown live on the service's [status](/docs/observability/status). A slow-booting release still reaches `applied` — the timeline's **Live** step shows when it is actually ready.

## The deploy timeline

Each deployment stamps a timestamp as it enters each phase — queued, build started, built, applied. The console renders them as a timeline with per-phase durations, updating live while the deploy runs.

`applied` is not the last step you see. Once the new version is actually observed ready, the timeline shows **Live** — the moment runtime truth caught up with the pipeline. A slow-booting release is applied well before it is live; the gap between the two steps is your app's boot time.

Build logs are attached to the deployment: open one to read its build output, streaming live while the build runs and kept afterwards.

The per-phase timestamps are on the deployment object; see the [Deployments API](/api/deployments) for the endpoints.

## Roll back

Rolling back never rewrites history. It creates a **new** deployment — the next version number — that re-applies the chosen version's frozen image and configuration snapshot through the normal pipeline, with no health guarantee: that release shipped before, but whether it still boots against today's data and dependencies shows up on the service's status, exactly like any deploy. The version you rolled back from stays in the history, and the rollback is recorded in the audit trail with the from and to versions.

From the console:

1. 
2. 
3.

Rolling back requires the editor role or higher — see [teams and roles](/docs/collaboration/teams-and-roles).

You can also roll back programmatically, authenticated with an [API token](/docs/developers/api-tokens):

```text
curl -X POST "https://api.koo.io/accounts/{accountId}/projects/{projectId}/environments/{environmentId}/services/{name}/rollback" \
  -H "Authorization: Bearer kc_…" \
  -H "Content-Type: application/json" \
  -d '{"version": 4}'
```

The response is the new deployment, starting at `queued` — the frozen image already exists, so there is no build.

> **Warning:**
>
> Rollback restores the configuration captured with that version, not just the image. Port, command, scaling, and environment changes made after that version shipped are reverted to the snapshot.

A rollback is rejected — with a clear reason, and without creating a new version — when the target is already the current version, when the version's internally built image is no longer available, or when its configuration references something that has since been deleted (for example, a removed sibling service).

## History retention

Deployment history is never pruned — every version stays listed. How far back you can roll back depends on your plan's history depth: versions beyond your plan's depth appear locked in the console, and the API rejects them with `quota_exceeded`. Upgrading your plan retroactively unlocks the older versions. See [the free tier](/docs/get-started/free-tier) and [billing](/docs/account/billing) for what each plan includes.

## Redeploy vs rollback

- 
-