Releases and deployments
How a release snapshots your project's configuration, how a deployment makes it live, and how to roll back or revoke one.
A release is a snapshot of your project's configuration. A deployment makes it live on the project's origins. Deploying is how an edit to .zitadel/ reaches users. The deploy guide has the commands.
Release
A release pins one revision of each schema, login flow, policy, identity provider connection and branding. It also records who built it, when, from which commit, and a message saying why.
- A release never changes. Building unchanged files returns the same release.
- A release belongs to one project.
zitadel release createbuilds a release without deploying it.
Deployment
A deployment puts a release live on a target: primary, meaning every primary origin at once, or a list of preview URLs. zitadel deploy deploys to primary and zitadel preview to a pull-request build's URLs.
A deployment freezes the project's variables for its target. Deployments form a history that is never edited; zitadel deployment list shows it, newest first.
Each origin is served the release of the newest deployment to it. A request with no origin, such as the CLI's or your backend's, and the console get the newest primary deployment's release; with no primary deployment yet, they are refused (rel.no_default). A sign-in stays on the release it started with, even if a newer deployment lands meanwhile.
Rollback
zitadel deployment rollback deploys an earlier primary deployment's release again, with the variable values it froze. Without an ID it undoes the last deploy. Users keep their data and schema revision; a rollback only changes configuration.
Revoked releases
zitadel release revoke <id> stops a release from being served or deployed again (409 rel.revoked), for example one with a broken flow that a rollback could bring back.
- A release an origin still serves cannot be revoked (
409 rel.in_use). The command names the first three origins that serve it and counts the rest;--jsonlists them all. Deploying another release frees a primary origin;zitadel preview rmfrees a preview, which also frees itself when it expires. - Revoking rarely affects users, because a sign-in keeps the release it started on. It fails at its next step only if it started before the newer deployment and is still running when you revoke.
Every origin of a project shares the same users and sessions; only configuration differs. Users that must stay apart, such as staging's, belong in a second project: a separate environment.
Was this helpful?