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,
- when it was created — who triggered it is recorded in the audit trail.
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 service'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.
Roll back through the API, authenticated with an API token. It requires the editor role or higher — see teams and roles.
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, and scaling changes made after that version shipped are reverted to the snapshot. Variables are not reverted — they are live state, not part of the snapshot — and the service's public networking also stays as it is.
A rollback is rejected — with a clear reason, and without creating a new version — when the target is already the current version, when the target version never shipped, when the version's internally built image is no longer available, or when its frozen configuration is no longer valid under today's rules (a version that carried a volume cannot be restored yet).
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: a rollback past that depth is rejected with quota_exceeded. Upgrading your plan retroactively unlocks the older versions. See usage & limits for each plan's history depth.
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.