Skip to content

Promote

Operations

Method Endpoint Description
POST /promote Promote changes into downstream variants

Promote changes into downstream variants

POST /promote

Moves changes from upstream Spaces into the downstream variants selected by WhereSpace, SpaceFilterID, ChangeOrderID and TargetStage, and makes them match: Units are upgraded, emptied, revived and cloned, clones are placed in the variant's namespace, and their Links are copied. With a ChangeOrder only its range is promoted, and with a ChangeWorkflow the Stage's entry gates are enforced. Promoting again changes nothing.

Operation ID: Promote

Parameters

Query Parameters

Parameter Type Required Description
dry_run boolean Plan the promotion, evaluate its gates, and return the same response without writing anything.
include string Comma-separated parts of the result to return in addition to the actions: Mutations for what each Unit write changed, or on a dry run would change. On a dry run it runs the merges a plan otherwise skips, so it is returned only when named.

Request Body

Content-Type: application/json

Schema: PromoteRequest

Responses

Status Description Content-Type Schema
200 OK application/json PromoteResult
207 Multi-Status: some Unit or Link writes failed, each carrying its own error application/json PromoteResult
400 Promote request is invalid (Bad Request). application/json StandardErrorResponse
401 Unauthorized access. application/json StandardErrorResponse
403 Forbidden access. application/json StandardErrorResponse
404 Promote not found. application/json StandardErrorResponse
409 The Stage's entry gates do not hold; the result names each gate and whether it holds. Nothing was written. application/json PromoteResult
412 The plan differs from ExpectedPlan. Nothing was written. application/json StandardErrorResponse
500 Something went wrong while processing Promote. application/json StandardErrorResponse
default Unexpected error. application/json StandardErrorResponse

Schemas

PromoteRequest

Properties

Property Type Required Description
ChangeDescription string Recorded on each Unit write.
ChangeOrderID string (uuid) The ChangeOrder to promote. Without one, everything each upstream has reached is promoted. With one, only its range is, into the Spaces it is headed for.
ChangeSetID string (uuid) An existing open ChangeSet to record every write in.
ExpectedPlan string The Plan a previous dry run returned. If the plan now differs, nothing is written and the request fails with 412.
Force boolean Promote even though the Stage's entry gates do not hold. Requires ForceReason, and Edit permission on the ChangeOrder, where the override is recorded.
ForceReason string Why the gates were overridden. Required with Force.
SpaceFilterID string (uuid) A Filter over Spaces selecting the Spaces to promote. Intersected with the other selectors.
Squash boolean Merge each Unit's range as one rebased Revision rather than replaying each upstream Revision.
TargetStage string A Stage of the ChangeOrder's ChangeWorkflow to promote into. Requires a ChangeOrder with a ChangeWorkflow. When empty, and neither WhereSpace nor SpaceFilterID is given, the next Stage the change has not reached.
WhereSpace string A where expression selecting the Spaces to promote. Intersected with the other selectors.

PromoteResult

Properties

Property Type Required Description
ChangeOrderID string (uuid)
Complete boolean Every Stage of the ChangeWorkflow already has the change; nothing was promoted.
DryRun boolean True when nothing was written.
Plan string Digest of the planned actions. Send it as ExpectedPlan to apply exactly this plan.
Spaces Array of PromoteSpaceResult In the order they were, or would be, promoted: a Space after any selected Space it takes from.
Stages Array of PromoteStageResult The Stages entered, each with every gate evaluated over the Stage before it.

StandardErrorResponse

Error response details.

Properties

Property Type Required Description
Code string HTTP status code of the response.
Message string Message returned with the response.