Deployments

Deployments — invoke a Deployment block (a node function + options, declared by a build or addressed directly by CID) and track it like a build. A deployment is side-effecting and never cached: every CreateDeployment runs.

Service builder.Deployments, 7 rpcs.

CreateDeployment(CreateDeploymentRequest) -> CreateDeploymentResponse

Start a deployment from a Deployment block CID (function + options), with optional labels and a display name. Returns the initial snapshot; the run proceeds in the background. NOT_FOUND if the CID is not a Deployment block.

Request: CreateDeploymentRequest

message CreateDeploymentRequest {
  optional string deployment_cid = 1;
  optional string name = 2;
  optional map<string, string> labels = 3;
  optional string source_build_id = 4;
}

Field
`deployment_cid`	CID of the Deployment block to run (function + options).
`name`	Optional display name and labels. `--name` travels as the `bldr.name` label (uniform with builds and runs); `name` is the older, equivalent channel and is still honoured.
`labels`
`source_build_id`	The build this was launched from, if any. Set by the daemon when a build's deploy target creates this run; a cross-link, not an instruction.

Response: CreateDeploymentResponse

message CreateDeploymentResponse {
  optional Deployment deployment = 1;
}

ListDeployments(ListDeploymentsRequest) -> ListDeploymentsResponse

All deployment runs, newest first.

Request: ListDeploymentsRequest

message ListDeploymentsRequest {
  // no fields
}

Response: ListDeploymentsResponse

message ListDeploymentsResponse {
  repeated Deployment deployments = 1;
}

Field
`deployments`	Newest first.

WatchDeployments(WatchDeploymentsRequest) -> stream ListDeploymentsResponse

Watch the whole deployment list live: the current list first, then a fresh full snapshot whenever any deployment is created, deleted, or changes state.

Request: WatchDeploymentsRequest

message WatchDeploymentsRequest {
  // no fields
}

Response: ListDeploymentsResponse

The same message as ListDeploymentsResponse.

GetDeployment(GetDeploymentRequest) -> GetDeploymentResponse

Snapshot of a single deployment run. NOT_FOUND if the id is unknown.

Request: GetDeploymentRequest

message GetDeploymentRequest {
  optional string deployment_id = 1;
}

Response: GetDeploymentResponse

message GetDeploymentResponse {
  optional Deployment deployment = 1;
  repeated TaskEvent tasks = 2;
}

Field
`deployment`
`tasks`	The deployment's progress tree as it stands: the latest event per node, roots first — the same compacted replay WatchDeploymentProgress leads with, for a reader that wants the tree once rather than a stream.

AbortDeployment(AbortDeploymentRequest) -> AbortDeploymentResponse

Cancel a running deployment. was_aborted = false if it was already terminal or unknown. The run stays in the list (state CANCELLED) until deleted.

Request: AbortDeploymentRequest

message AbortDeploymentRequest {
  optional string deployment_id = 1;
}

Response: AbortDeploymentResponse

message AbortDeploymentResponse {
  optional bool was_aborted = 1;
}

Field
`was_aborted`	False if the run was already terminal or unknown.

DeleteDeployment(DeleteDeploymentRequest) -> DeleteDeploymentResponse

Remove a deployment run from the list. was_deleted = false if unknown.

Request: DeleteDeploymentRequest

message DeleteDeploymentRequest {
  optional string deployment_id = 1;
}

Response: DeleteDeploymentResponse

message DeleteDeploymentResponse {
  optional bool was_deleted = 1;
}

Field
`was_deleted`	False if the deployment_id was unknown.

WatchDeploymentProgress(WatchDeploymentProgressRequest) -> stream DeploymentEvent

Subscribe to a deployment's events: the current snapshot first, then live events (progress-tree TaskEvents + terminal snapshots). Detached: cancelling has no effect on the run.

Request: WatchDeploymentProgressRequest

message WatchDeploymentProgressRequest {
  optional string deployment_id = 1;
}

Response: DeploymentEvent

Streamed by WatchDeploymentProgress: a leading snapshot, then live events.

message DeploymentEvent {
  oneof event {
    Deployment snapshot = 1;
    TaskEvent task = 2;
  }
}

Field
`snapshot`
`task`	A node in the deployment's progress tree (the function's invocation tree).

Types used above

Deployment

A deployment run: one invocation of a Deployment block's function over its options, tracked with a progress tree. Returned by Create/Get/List and carried as the leading snapshot event on WatchDeploymentProgress.

message Deployment {
  optional string id = 1;
  optional string name = 2;
  optional string deployment_cid = 3;
  optional string function = 4;
  optional map<string, string> labels = 5;
  optional DeploymentState state = 6;
  optional string output_cid = 7;
  optional string error = 8;
  optional string source_build_id = 9;
  optional int64 created_at_seconds = 10;
  optional int64 started_at_seconds = 11;
  optional int64 finished_at_seconds = 12;
}

Field
`id`
`name`	Human display name (defaults to the deployment name or the function).
`deployment_cid`	CID of the Deployment block (function + options) being run.
`function`	The node function invoked (read from the Deployment block).
`labels`	Free-form labels attached at create time. `bldr.name` is the well-known key carrying the user's `--name`; when set, `name` above resolves to it.
`state`
`output_cid`	The invocation's output CID, set once the run SUCCEEDS.
`error`	Set when state == FAILED.
`source_build_id`	The build this deployment was started from, if any (for cross-linking).
`created_at_seconds`	Unix seconds.
`started_at_seconds`
`finished_at_seconds`

DeploymentState

enum DeploymentState {
  DEPLOYMENT_STATE_UNSPECIFIED = 0;
  DEPLOYMENT_STATE_PENDING = 1;
  DEPLOYMENT_STATE_RUNNING = 2;
  DEPLOYMENT_STATE_SUCCEEDED = 3;
  DEPLOYMENT_STATE_FAILED = 4;
  DEPLOYMENT_STATE_CANCELLED = 5;
}

Value
`DEPLOYMENT_STATE_UNSPECIFIED`
`DEPLOYMENT_STATE_PENDING`	created, run not started yet
`DEPLOYMENT_STATE_RUNNING`	the deployment function is executing
`DEPLOYMENT_STATE_SUCCEEDED`	finished; output_cid is set
`DEPLOYMENT_STATE_FAILED`	finished; error is set
`DEPLOYMENT_STATE_CANCELLED`	aborted before finishing

Deployments

On this page