Promoting between environments
Promoting means shipping to one service the version already built and verified on another. Nothing is rebuilt along the way.
Why publishing the same commit is not enough
Two builds of the same code frequently produce different images — base images that moved, dependencies resolved at another moment, embedded timestamps.
This is not theory. On 2026-08-27 the same platform commit was built twice, on the same machine, minutes apart, and produced two distinct artifacts.
If promotion rebuilt, what was tested and what shipped would be different objects — and the difference would show up exactly when nobody could afford it.
The Zero rule: build once, promote many.
From the console
- Open Services and find the source service — the one with the approved version.
- Click Promote, next to the version identifier.
- Pick the destination service.
- Confirm.
The screen shows which version will ship and where, before anything happens.
From the command line
# promotes the ACTIVE version of the source
zero promote web-prod --from web-preview
# or a specific version
zero promote web-prod --release rel_01K...
zero promote web-prod --artifact art_01K...
# the versions already built for a service, each with its digest
zero artifacts web-preview
--from resolves the source's active version, not the latest one. The difference shows after a rollback: the latest is the one that failed; the active one is the one serving traffic.
From the API
Promotion is the same deployment operation, with the artifact in place of the source:
POST /api/v1/services/{id}/deployments
Idempotency-Key: 4f7c...
{ "artifact_id": "art_01K..." }
source and artifact_id together are refused with 422. Whoever sends both usually means "rebuild from here and promote" — and those are different things.
What promotion carries, and what it does not
| Travels with it | Stays at the destination |
|---|---|
| The exact image, identified by content | Environment variables |
| The source commit, for traceability | Secrets |
| Domain and address | |
| Scale and resources |
Configuration belongs to the environment, never to the artifact. That is what lets the same image serve preview and production with different credentials.
When the platform refuses
| Situation | Response |
|---|---|
| Artifact from another organization | 404 — the same answer as "does not exist", so nothing can be enumerated |
| Artifact from another project | 409 — the promotion boundary is the project |
| Artifact not verified yet | 409 — the platform only promotes what it has checked |
| You only have read permission | 403 |
The boundary being the project is deliberate: between services of the same project it is exactly the move promotion exists for; across projects it would inject one application's image into another.
Going back
Promoting deletes nothing. The destination's previous version stays intact, and returning to it also does not rebuild — it is a pointer swap. See Restoring a version.
Was this page helpful?
Report a problem on this pageDo not send passwords, keys, tokens, or customer data.