Deployments API

Get a deployment

waitingFor is set while the deployment waits for an offline server.

Cancel a deployment at any step

Before the agent acknowledged the deployment's command the deployment ends as canceled at once. Once the agent runs it, a cancel request is sent to the agent (cancelRequestedAt is set) and the deployment ends as canceled when the agent reports back, with the step it reached in canceledAtStep: a pull or build is stopped (a build's work directory is removed), containers of the new release are removed and the current release keeps serving, during verification the previous routes are restored first, and a recreate deploy that already stopped the previous release starts it again. If the previous release cannot be restored the result is rollback_failed with manual recovery steps. Once the new release is live it is too late: the deployment finishes (a still-running post-deploy command is stopped). An offline server receives the request when it reconnects. A finished deployment is 409 cannot_cancel.

A deployment's agent commands, redacted

Every command the control plane sent for the deployment (deploy, build_image, cancel_deploy, …): kind, server, delivery state, enqueue/ack/finish times, outcome and error, with the payload and result as persisted. Variable values, tokens, credentials and file contents never appear: those fields are masked. Needs the same access as the deployment's logs.

A deployment's step timeline

The release a deployment shipped, for debugging

The release id and generation, the resolved source (image ref and digest, or git commit), how it was built and where it ran, the configuration snapshot with secrets and file contents masked, and the keys of its variables with which are secret, references or provided by the platform. Never a variable value. 404 when the deployment has no release yet.

Roll back to the release of a successful deployment

Application image and configuration only. Databases, volumes and external services are not rolled back. Creates a new deployment of the old release (rolledBackFrom is the deployment that was running). A git release whose built image was pruned returns 409 image_pruned with commitSha in the details: rebuild the commit instead.

Deploy every service with staged changes

Services start in reference order: providers of ${{service.KEY}} references first (otherwise databases first; a reference cycle keeps the input order). A consumer's deployment waits until the providers of the same batch finished (at most 10 minutes). order lists the service ids in the order they were started. Services that cannot deploy are skipped unless named in serviceIds.

List the deployments of every service of an environment (newest first)

Filter by status (comma-separated) and serviceId.

Deployment outcomes per UTC day for an environment

One entry per day, oldest first, ending today (days 1..90, default 30); days without deployments are zeros. failed counts failed and rollback_failed, other counts canceled, rolled_back and in-flight deployments.

Preview how a git service would be built

Asks the agent of the service's server to clone the branch head and report the build method (the repository's Dockerfile, Railpack or a generated starter Dockerfile), why it applies, and for Railpack the detected providers, packages, steps and start command. Nothing is built or deployed. The request waits for the agent (up to 150 s): 409 server_offline when the server is offline, 504 build_plan_timeout when it does not answer. Requires deployments:write because it makes the server clone the repository and run the planner.

List a service's deployments (newest first)

Deploy a service

Returns 202 with the deployment; it runs asynchronously. 409 deployment_in_progress while another deployment of the service is active; 422 for blocking problems (no server, revoked server, unresolved variable references).

Plan a deployment (dry run)

Reports the strategy (rolling or recreate, with reasons), warnings, the pending changes, the resolved source and blocking problems. Nothing is started.