Deployments & rollback
Every deploy 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:
- a version — a number that only counts up per service (v1, v2, v3, …),
- the image that shipped,
- a frozen snapshot of the service's configuration at deploy time,
- who triggered it and when.
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.
Deployment statuses
| Status | Meaning |
|---|---|
queued | Accepted, waiting for the pipeline: for a build to start, or — for deploys that ship an existing image, including rollbacks — for the release to be applied. |
building | A build is producing the image. Deploys that ship an existing image skip the build statuses. |
built | The image is ready; the release is being applied to Koo's hosting layer. |
applied | Koo's hosting layer accepted the new version — the pipeline finished. |
failed | The pipeline couldn't ship the release: the build failed, or the release couldn't be applied. The errors are recorded on the deployment. |
superseded | A newer deploy took over before this one finished. |
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. 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 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:
- Open the service and go to its Deployments tab.
- Find the version you want to return to and click Roll back.
- Confirm in the dialog — it shows the image being restored and what the rollback changes.
Rolling back requires the editor role or higher — see teams and roles.
You can also roll back programmatically, authenticated with an API token:
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.
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 and billing for what each plan includes.
Redeploy vs rollback
- Redeploy ships something new: you update the image or configuration, and the next version is built and applied from that. Use it to fix forward.
- Rollback returns to a known-good version: a new version reusing a frozen release — no build, the exact image and configuration that already shipped. Use it to recover fast, then fix forward with a redeploy.