roll_back #

View this page as Markdown

On this page

Generated automatically from the published contract sources.

A script calls this action over HTTPS at POST https://tzcloud.turnzero.ai/v1/roll_back, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool tzcloud_roll_back.

OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts (Sign-in, sessions, and tokens).

Build metadata: Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.

Contract description #

Put earlier deployed code on production with that version's setting bindings and plain values. The serving version draws version_already_serving, a newer one version_newer_than_serving. With none serving, no comparison is made. With one or two environments, take a promotable number from list_versions. Across model changes, the account owner decides on data. No action offers snapshots yet. If halted, it refuses target_environment_halted. First use halt_environment with resume: true. The owner must agree or have asked.

An answer not from this platform does not show whether the rollback started. Examples are gateway error pages or closed connections. Call read_status with wait_seconds first. It started if environments.production.deploy shows kind promote with a started_at later than your call. Rollbacks use that kind. Repeat roll_back only if that read shows it did not start.

More about this action #

A rollback works on an application with one environment too: pass one of production's own earlier versions.

The wait_seconds argument: optional, a whole number of seconds from 1 to 45, counted from the call's arrival. The call waits for the version-history row it started, and replies when that row ends or the seconds pass. Each server holds one wait per application. This call's wait takes that place. A concurrent held read_status for that application on the same server returns at once, from its own read. A value outside 1 to 45 is refused invalid_request, and its detail gives 45 as the bound. Without wait_seconds, the call returns 202 at once with the state deploying.

With wait_seconds, up to 45, it waits to reply until the rollback ends, as a promote does. A rollback ends once every router serves that version, typically after 33 to 45 seconds. Choose a version whose image is kept, marked promotable by list_versions. A version whose image retention deleted is refused version_image_pruned; choose a kept version or deploy that code again. If version_newer_than_serving refuses the rollback, use promote with two environments, or deploy that code again with one. To re-mint the serving version's platform credential, use promote on two environments, or deploy again on one.

Access and action metadata #

{
  "name": "roll_back",
  "resource": "environment",
  "tier": "reversible",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "clients": [
    "bearer",
    "browser_session"
  ],
  "product": "cloud",
  "summary": "Put an earlier version back into production with that version's code, setting bindings and plain values. The serving version is refused `version_already_serving`, and a newer one `version_newer_than_serving`. It replies and waits as a promote does, `wait_seconds` up to 45 holding its answer until it ends. It works on an application with one environment too, where you pass one of production's own earlier versions.\n\nAn answer that is not this platform's own, such as a gateway's error page or a closed connection, says nothing about whether the rollback was made. Read `read_status` with `wait_seconds` first: the rollback started where `environments.production.deploy` shows the kind promote, which a rollback's row has, with a `started_at` later than your call. Call `roll_back` again only where that read shows it did not start.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "openWorldHint": true
  }
}

MCP catalog entry #

{
  "name": "roll_back",
  "title": "Roll back production",
  "tier": "reversible",
  "scenario": "CHI-L0-09",
  "summary": "Put earlier deployed code on production with that version's setting bindings and plain values. The serving version draws `version_already_serving`, a newer one `version_newer_than_serving`. With none serving, no comparison is made. With one or two environments, take a `promotable` number from `list_versions`. Across model changes, the account owner decides on data. No action offers snapshots yet. If halted, it refuses `target_environment_halted`. First use `halt_environment` with `resume: true`. The owner must agree or have asked.\n\nAn answer not from this platform does not show whether the rollback started. Examples are gateway error pages or closed connections. Call `read_status` with `wait_seconds` first. It started if `environments.production.deploy` shows kind promote with a `started_at` later than your call. Rollbacks use that kind. Repeat `roll_back` only if that read shows it did not start.",
  "owners": [
    "PLD-L0-57",
    "PLD-L0-43",
    "MAPI-04"
  ]
}

request #

JSON pointer Description and constraints
"" (root) Type: object
Required fields: ["application","version"]
/properties/application Your account's application id from list_applications, not its name or label.

Type: string
/properties/version A deployed number from list_versions with promotable true. Where production serves a version, choose an earlier number: the serving version is refused version_already_serving, and a newer one version_newer_than_serving.

Type: integer
Minimum: 1
/properties/wait_seconds Seconds to hold the answer until the version-history row this call starts ends. A value out of range is refused invalid_request.

Type: integer
Minimum: 1
Maximum: 45

response #

JSON pointer Description and constraints
"" (root) A rollback is a promote of the version you pass; it re-mints the production platform credential as every promote does and never the database credential. It replies, and holds a wait, as a promote does. It works on an application with one environment too, where the version you pass is one of production's own earlier deployed rows.

Type: object
Required fields: ["contract_version","application","environment","version","state","hostname"]
/properties/contract_version Required value: 1
/properties/reference The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call.

Type: string
Pattern: ^[0-9a-f]{10}$
/properties/summary The answer's first member: one sentence giving the environment's state and serving version and, for the row this call started, its version, kind, step, and seconds since it started, or how it ended.

Where this call's held answer ends deployed on production, the summary may close with an invitation warning. This applies to an invited audience whose production realm is absent, or holds no end user other than test end users and no standing invitation. The warning says no invited user can sign in to production yet and tells the caller to use invite_end_user. It is added last, only if the whole summary fits its budget. A failed realm read adds no warning.

Type: string
/properties/application Type: string
/properties/environment Always production: a promote targets production alone.

Type: string
Pattern: ^production$
/properties/version The promoted number, an existing number of the application's history and never a fresh one.

Type: integer
/properties/state deploying on the 202 answer, which precedes the row's end. The state is deployed or failed on the 200 answer, where the request's wait_seconds saw the row end.

Type: string
Pattern: ^(deploying|deployed|failed)$
/properties/hostname Type: string
/properties/health_path The recorded manifest's health path, which the health gate that follows this act will probe, cut at 256 characters as the gate's record keeps it. It is absent only where the recorded manifest holds no health path, which the manifest's schema admits nowhere.

Type: string
/properties/settled Present where the request carried wait_seconds. True where the one read after the wait found the row this call started ended, whatever ended the wait. False means that read found the row still deploying, or could not read it, and not that it failed: next gives the call that waits on it.

Type: boolean
/properties/waited_ms Present where the request carried wait_seconds: the milliseconds the answer was held after the row started.

Type: integer
Minimum: 0
/properties/outcome Present where the wait settled: the row's outcome as list_versions returns it. Its result is succeeded on a deployed row and failed, interrupted, or superseded on a failed one.

Type: object
/properties/next Present where the answer is 202 with the state deploying: at once without wait_seconds, and where the wait did not settle. It is the exact call that reads the row to its end, read_status for production, with wait_seconds 45.

Type: object
Required fields: ["action","arguments"]
Additional properties: false
/properties/next/properties/action Required value: read_status
/properties/next/properties/arguments Type: object
Required fields: ["application","environment","wait_seconds"]
Additional properties: false
/properties/next/properties/arguments/properties/application Type: string
/properties/next/properties/arguments/properties/environment Required value: production
/properties/next/properties/arguments/properties/wait_seconds Required value: 45
/properties/detail With the state deploying, says how the rollback's step and end are read: the next call, read_status with wait_seconds 45, or a read every ten seconds.

With deployed or failed, says how the row ended. For a deployed run that entered health_gate, it says the check requested the health path alone, with no smoke path requested. It says to request the other routes, read read_status's server_errors, and read read_logs for errors.

With deployed and a run that entered no health_gate, it says no health check or smoke check ran and to request its pages or routes and read read_logs for errors. A row with no step list uses the health-check form.

Type: string

Complete payload contract #

{
  "request": {
    "type": "object",
    "required": [
      "application",
      "version"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "Your account's application `id` from `list_applications`, not its name or label."
      },
      "version": {
        "type": "integer",
        "minimum": 1,
        "description": "A deployed number from `list_versions` with `promotable` true. Where production serves a version, choose an earlier number: the serving version is refused `version_already_serving`, and a newer one `version_newer_than_serving`."
      },
      "wait_seconds": {
        "type": "integer",
        "minimum": 1,
        "maximum": 45,
        "description": "Seconds to hold the answer until the version-history row this call starts ends. A value out of range is refused `invalid_request`."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "application",
      "environment",
      "version",
      "state",
      "hostname"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "reference": {
        "type": "string",
        "pattern": "^[0-9a-f]{10}$",
        "description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call."
      },
      "summary": {
        "type": "string",
        "description": "The answer's first member: one sentence giving the environment's state and serving version and, for the row this call started, its version, kind, step, and seconds since it started, or how it ended (PLD-L0-63).\n\nWhere this call's held answer ends `deployed` on production, the summary may close with an invitation warning. This applies to an `invited` audience whose production realm is absent, or holds no end user other than test end users and no standing invitation. The warning says no invited user can sign in to production yet and tells the caller to use `invite_end_user`. It is added last, only if the whole summary fits its budget. A failed realm read adds no warning."
      },
      "application": {
        "type": "string"
      },
      "environment": {
        "type": "string",
        "pattern": "^production$",
        "description": "Always `production`: a promote targets production alone (PLD-L0-43)."
      },
      "version": {
        "type": "integer",
        "description": "The promoted number, an existing number of the application's history and never a fresh one (PLD-L0-43)."
      },
      "state": {
        "type": "string",
        "pattern": "^(deploying|deployed|failed)$",
        "description": "`deploying` on the 202 answer, which precedes the row's end. The state is `deployed` or `failed` on the 200 answer, where the request's `wait_seconds` saw the row end."
      },
      "hostname": {
        "type": "string"
      },
      "health_path": {
        "type": "string",
        "description": "The recorded manifest's health path, which the health gate that follows this act will probe, cut at 256 characters as the gate's record keeps it. It is absent only where the recorded manifest holds no health path, which the manifest's schema admits nowhere (PLD-L0-63)."
      },
      "settled": {
        "type": "boolean",
        "description": "Present where the request carried `wait_seconds`. True where the one read after the wait found the row this call started ended, whatever ended the wait. False means that read found the row still deploying, or could not read it, and not that it failed: `next` gives the call that waits on it (MAPI-04; PLD-L0-63)."
      },
      "waited_ms": {
        "type": "integer",
        "minimum": 0,
        "description": "Present where the request carried `wait_seconds`: the milliseconds the answer was held after the row started."
      },
      "outcome": {
        "type": "object",
        "description": "Present where the wait settled: the row's `outcome` as `list_versions` returns it. Its `result` is `succeeded` on a deployed row and `failed`, `interrupted`, or `superseded` on a failed one (PLD-L0-63)."
      },
      "next": {
        "type": "object",
        "required": [
          "action",
          "arguments"
        ],
        "properties": {
          "action": {
            "const": "read_status"
          },
          "arguments": {
            "type": "object",
            "required": [
              "application",
              "environment",
              "wait_seconds"
            ],
            "properties": {
              "application": {
                "type": "string"
              },
              "environment": {
                "const": "production"
              },
              "wait_seconds": {
                "const": 45
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false,
        "description": "Present where the answer is 202 with the state `deploying`: at once without `wait_seconds`, and where the wait did not settle. It is the exact call that reads the row to its end, `read_status` for `production`, with `wait_seconds` 45."
      },
      "detail": {
        "type": "string",
        "description": "With the state `deploying`, says how the rollback's step and end are read: the `next` call, `read_status` with `wait_seconds` 45, or a read every ten seconds (MAPI-04).\n\nWith `deployed` or `failed`, says how the row ended. For a deployed run that entered `health_gate`, it says the check requested the health path alone, with no smoke path requested. It says to request the other routes, read `read_status`'s `server_errors`, and read `read_logs` for errors.\n\nWith `deployed` and a run that entered no `health_gate`, it says no health check or smoke check ran and to request its pages or routes and read `read_logs` for errors. A row with no step list uses the health-check form."
      }
    },
    "description": "A rollback is a promote of the version you pass; it re-mints the production platform credential as every promote does and never the database credential (PLD-L0-43; SEC-L0-07). It replies, and holds a wait, as a promote does. It works on an application with one environment too, where the version you pass is one of production's own earlier deployed rows (PLD-L0-43)."
  }
}

Shared contracts #