Docs

Roll back to a deployment

POST
/deployments/{deployment_id}/rollback

Re-deploys the release of the deployment named in the path to primary, with the variable values it froze: a new deployment with reason: rollback and rollback_to naming it. Like any deployment to primary, it covers every current primary origin. Idempotent like a deployment to primary: when nothing would change it answers 200 with the newest primary deployment.

Failures:

  • 400 dep.invalid: the deployment went to preview URLs (deploy to the preview again instead), or the project has no primary origin.
  • 404 dep.not_found: no deployment of the project has that id.
  • 409 dep.conflict: expected_deployment_id is not the project's newest primary deployment; details.deployment is that deployment.
  • 409 rel.revoked: the release is revoked.

Authorization

headerAuthorizationBearer <token>

Scope: deployment.write

Path Parameters

deployment_id*string

The unique identifier of the deployment.

Match^dep_[a-zA-Z0-9_-]+$

Query Parameters

project_id*string

The unique identifier of the project

Match^[a-zA-Z0-9_-]+$

Request Body

application/json
  1. body

What to record alongside the rollback; the release, variable values and targets are not chosen here.

message?string

A short free-form summary of why the rollback happened. Recorded on the new deployment's metadata.

Lengthlength <= 1024
expected_deployment_id?deployment-id

Roll back only if the project's newest primary deployment is this one. Otherwise the request fails with 409 dep.conflict and nothing changes. Not stored.

Match^dep_[a-zA-Z0-9_-]+$

Response Body

Nothing changed. The body is the newest primary deployment, with its own reason, message and deployed_at.

application/json
  1. response

An immutable record of a release made live on a set of targets. Deploying and rolling back each append one, so the history is the audit trail.

All primary origins serve the project's newest primary deployment; one added after it serves nothing until the next deployment to primary. A preview URL serves the newest deployment to it while its preview is live.

Every field is fixed at creation except status, which is read as of now.

id*deployment-id

The opaque, immutable resource id, assigned at creation.

Match^dep_[a-zA-Z0-9_-]+$
project_id*project-id

The project this deployment belongs to.

Match^[a-zA-Z0-9_-]+$
release_id*release-id

The release this deployment made live. Always the release id, also when the request named the release by content_hash.

Match^rel_[a-zA-Z0-9_-]+$
kind*DeploymentKind

primary for the project's primary origins, preview for preview URLs.

Value in"primary""preview"
targets*array<>

The resolved origins, sorted. For primary, the project's primary origins at creation. The live view lists only the targets still served.

Items1 <= items
status*DeploymentStatus

Whether the deployment serves its release now.

  • live — at least one of its targets serves it now.
  • inactive — none does: a later deployment replaced it, or its previews expired or were removed.
Value in"live""inactive"
deployed_at*string

When the deployment was created.

Formatdate-time
metadata*

Why the release went live and who made it happen.

release?

The release named by release_id, present only when the request asked for it with expand: ["release"] — the same representation GET /releases/{release_id} serves. Absent means it was not requested.

Example Request
import { configureZitadel, getApi } from "@zitadel/api/config";import { setApiCsrfToken } from "@zitadel/api/runtime/auth";// In the browser, through the SDK proxy: the session cookie authenticates the call.const client = getApi(configureZitadel({ projectId: "proj_01KWH1P4MYS7F0N9WD3P2E4YM5" }));// A write the session cookie authenticates carries the session's CSRF token.setApiCsrfToken((await client.getMySessionCsrfToken()).csrf_token);const deployment = await client.rollbackDeployment(  "dep_01KX4SB9C8E1F0N9WD3P2E4YM5",  { project_id: "proj_01KWH1P4MYS7F0N9WD3P2E4YM5" },  { message: "phone_number broke sign-up" },);
Example Response
{  "id": "string",  "project_id": "string",  "release_id": "string",  "kind": "primary",  "targets": [    {      "origin": "string",      "expires_at": "2019-08-24T14:15:22Z"    }  ],  "status": "live",  "deployed_at": "2019-08-24T14:15:22Z",  "metadata": {    "reason": "deploy",    "message": "string",    "rollback_to": "string",    "deployed_by": "string",    "deployed_by_type": "human"  },  "release": {    "id": "string",    "project_id": "string",    "content_hash": "stringstringstringstringstringstringstringstringstringstringstringstrin",    "metadata": {      "message": "string",      "git_sha": "string",      "git_dirty": false,      "created_at": "2019-08-24T14:15:22Z",      "created_by": "string",      "created_by_type": "human"    },    "revoked_at": "2019-08-24T14:15:22Z",    "pointers": [      {        "kind": "schema",        "handle": "string",        "revision_id": "string"      }    ]  }}

Was this helpful?