promote #

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/promote, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool tzcloud_promote.

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 #

Promote a version with production's settings and credentials. It re-mints production's platform credential. With no prior deploy, it creates production and starts its meters. It adds a database and owner role if the manifest declares one. On one environment, deploy to production or use roll_back. create_environment adds development. Deploy to development first. Halted production refuses promotes until resumed with halt_environment (resume: true). With no version passed and none serving there, it refuses nothing_to_promote. The account owner must have requested or agreed to this promote.

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

More about this action #

A promote reuses the image built when the version was deployed. A version whose image the platform has since deleted under its retention rules is refused version_image_pruned. With wait_seconds, up to 45, the call waits until the promote ends before it replies, and the answer starts with a one-line summary. An answer that did not settle gives the next call. Without wait_seconds, the call replies at once with the same next, and the promote finishes in the background. Read its end through read_status or list_versions, which show its step while it runs. A promote shows deployed once every router reaches the new version, typically after 33 to 45 seconds, so one wait usually covers it. The health check's own limit is 180 seconds.

The wait_seconds argument: the seconds, 1 to 45, counted from the call's arrival, that the call waits for the version-history row it started. It replies when that row ends or the seconds pass. Left out, the call returns 202 at once with the state deploying. 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 that range is refused invalid_request, and its detail gives 45 as the bound.

Pass a deployed number from list_versions with promotable true, or omit version to use development's serving version. On an application with one environment, promote is refused environment_not_created: a deploy already reaches production. A promote binds the current manifest, unlike a rollback. A missing bound secret draws setting_secret_missing; make the next store_secret call, then promote again. Halted production draws target_environment_halted; call halt_environment with environment: production and resume: true first. You can also use turnzero promote --application <id> [--version-number <n>] [--origin <origin>], which waits up to 45 seconds and never rotates the database credential.

Access and action metadata #

{
  "name": "promote",
  "resource": "environment",
  "tier": "reversible",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "product": "cloud",
  "summary": "Promote a version the history holds to production with production's own settings and credentials: the development environment's serving version, or the version you pass. It reuses the image built at deploy, so a version whose image the platform's retention deleted is refused `version_image_pruned`. It replies at once with the state `deploying` and `next`, and completes detached, read to its end through `read_status` and `list_versions`. With `wait_seconds` up to 45 it holds its answer until the promote ends, leading with a `summary`; an answer that did not settle gives the `next` call. On an application with one environment, whose deploy reaches production itself, it is refused `environment_not_created`, and the refusal gives `create_environment` and `roll_back`.\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 promote was made. Read `read_status` with `wait_seconds` first: the promote started where `environments.production.deploy` shows the kind promote with a `started_at` later than your call. Call `promote` again only where that read shows it did not start.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "openWorldHint": true
  }
}

MCP catalog entry #

{
  "name": "promote",
  "title": "Promote to production",
  "tier": "reversible",
  "scenario": "CHI-L0-07",
  "summary": "Promote a version with production's settings and credentials. It re-mints production's platform credential. With no prior deploy, it creates production and starts its meters. It adds a database and owner role if the manifest declares one. On one environment, deploy to production or use `roll_back`. `create_environment` adds development. Deploy to development first. Halted production refuses promotes until resumed with `halt_environment` (`resume: true`). With no version passed and none serving there, it refuses `nothing_to_promote`. The account owner must have requested or agreed to this promote.\n\nAn answer not from this platform does not show whether the promote started. Examples are gateway error pages or closed connections. Call `read_status` with `wait_seconds` first. The promote started if `environments.production.deploy` shows kind promote with a `started_at` later than your call. Repeat `promote` only if that read shows it did not start.",
  "owners": [
    "PLD-L0-43",
    "PLD-L0-63",
    "DBS-L0-02",
    "SEC-L0-07",
    "MAPI-04"
  ]
}

request #

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

Type: string
/properties/version Optional: a deployed, unretired number from either environment in list_versions, marked promotable; omitted, development's serving version is promoted.

Type: integer
Minimum: 1
/properties/rotate_database_credential Optional; absent, false. Where true and the manifest declares the database kind, the promote also re-mints the production database role's password under the same window as the platform credential, the production database's rotation act. The value is never returned.

Type: boolean
/properties/wait_seconds Optional: seconds to hold the answer until the promote ends; absent, it returns at once. Out of range is refused invalid_request.

Type: integer
Minimum: 1
Maximum: 45

response #

JSON pointer Description and constraints
"" (root) Returns 202 at once with next where the request carries no wait_seconds: the promote's history row is inserted and the work continues detached; its end is read through read_status and list_versions, never through the action record. With wait_seconds, the answer is held until the row ends: settled, it is 200 with the state deployed or failed and the row's outcome; unsettled, it is 202 with next. On an application with one environment, whose deploy reaches production itself, promote is refused environment_not_created before any other check, its detail giving roll_back and create_environment.

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/server_errors_since Present where the wait saw the row end deployed: the router's 5xx responses since the version began serving, as check_deploy's last_release counts them. count runs from since, the later of the row's end and seven days before the read. It is capped at 500, and capped is true where the cap was met, the count then a floor. It covers only the routes requested in that time, so a route nobody requested counts nothing. A route listed in the manifest's smoke_paths is checked before each deploy and promote switches, and that check is not in this count. Where the read failed, unread carries its reason. Absent on every other response.

/properties/server_errors_since/oneOf/0 Type: object
Required fields: ["count","since","capped"]
/properties/server_errors_since/oneOf/0/properties/count Type: integer
Minimum: 0
Maximum: 500
/properties/server_errors_since/oneOf/0/properties/since Type: string
/properties/server_errors_since/oneOf/0/properties/capped Type: boolean
/properties/server_errors_since/oneOf/1 Type: object
Required fields: ["unread"]
Additional properties: false
/properties/server_errors_since/oneOf/1/properties/unread Why the count was not read: failed, timed_out, or read_status's own word for its server_errors member, such as unavailable.

Type: string
/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 promote'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 and any smoke paths the manifest lists. It says to request the other routes, read read_status's server_errors, and read read_logs for errors. That form says a promote requests none where production already serves the version.

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"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "Your account's application `id` from `list_applications`, not its name or label."
      },
      "version": {
        "type": "integer",
        "minimum": 1,
        "description": "Optional: a deployed, unretired number from either environment in `list_versions`, marked `promotable`; omitted, development's serving version is promoted."
      },
      "rotate_database_credential": {
        "type": "boolean",
        "description": "Optional; absent, false. Where true and the manifest declares the database kind, the promote also re-mints the production database role's password under the same window as the platform credential, the production database's rotation act. The value is never returned."
      },
      "wait_seconds": {
        "type": "integer",
        "minimum": 1,
        "maximum": 45,
        "description": "Optional: seconds to hold the answer until the promote ends; absent, it returns at once. 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)."
      },
      "server_errors_since": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "count",
              "since",
              "capped"
            ],
            "properties": {
              "count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 500
              },
              "since": {
                "type": "string"
              },
              "capped": {
                "type": "boolean"
              }
            }
          },
          {
            "type": "object",
            "required": [
              "unread"
            ],
            "properties": {
              "unread": {
                "type": "string",
                "description": "Why the count was not read: `failed`, `timed_out`, or `read_status`'s own word for its `server_errors` member, such as `unavailable`."
              }
            },
            "additionalProperties": false
          }
        ],
        "description": "Present where the wait saw the row end `deployed`: the router's 5xx responses since the version began serving, as `check_deploy`'s `last_release` counts them. `count` runs from `since`, the later of the row's end and seven days before the read. It is capped at 500, and `capped` is true where the cap was met, the count then a floor. It covers only the routes requested in that time, so a route nobody requested counts nothing. A route listed in the manifest's `smoke_paths` is checked before each deploy and promote switches, and that check is not in this count. Where the read failed, `unread` carries its reason. Absent on every other response."
      },
      "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 promote'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 and any smoke paths the manifest lists. It says to request the other routes, read `read_status`'s `server_errors`, and read `read_logs` for errors. That form says a promote requests none where production already serves the version.\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": "Returns 202 at once with `next` where the request carries no `wait_seconds`: the promote's history row is inserted and the work continues detached; its end is read through `read_status` and `list_versions`, never through the action record (PLD-L0-63; MAPI-04). With `wait_seconds`, the answer is held until the row ends: settled, it is 200 with the state `deployed` or `failed` and the row's `outcome`; unsettled, it is 202 with `next` (MAPI-04; PLD-L0-63). On an application with one environment, whose deploy reaches production itself, `promote` is refused `environment_not_created` before any other check, its detail giving `roll_back` and `create_environment` (PLD-L0-43; PLD-L0-96)."
  }
}

Shared contracts #