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 Deprecated: use DryRun in the request body. Plan the promotion, evaluate its gates, and return the same response without writing anything. Either one asks for a dry run.
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, as entries of its MutationSources, and Diff for the same change path by path with the values on both sides, and ConfigData for the configuration each Unit write produced, or on a dry run would produce. On a dry run any of them runs the merges a plan otherwise skips, so they are returned only when named. Context, with Diff, adds to each Diff the unchanged paths around the changes: every unchanged child of each map or array that holds a change, up to the resource, as ChangeType None. Supported values: Mutations, Diff, Context, ConfigData.

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.
Clearance The guarded reasons the writes are cleared for. A path whose guards this does not cover is not written, and the withheld change is reported in the Unit's Conflicts.
DryRun boolean Plan the promotion, evaluate its gates, and return the same response without writing anything.
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.
Guards Reasons to record on the paths each Unit write changes. A later operation must be cleared for them before overwriting those paths. Clearance must cover them, since a write is withheld by guards it is not cleared for, its own included.
PriorRevisions string With a ChangeOrder, what to do for a Unit whose last merged upstream Revision is before the ChangeOrder's start there -- typically because a Link in the upstream Space, such as a TransformPaths Link, wrote Revisions after the Unit last merged. Include merges those Revisions first, as Revisions of their own that do not carry the ChangeOrder, and then the ChangeOrder's range; Skip merges only the ChangeOrder's range, as though the Unit had already merged as far as its start, and those Revisions do not arrive later; Error refuses, naming the Revisions; All merges them as Include does, and also marks every Unit in the Space the change does not change at its head, so the next promotion brings it up to this Space. Defaults to the ChangeOrder's PriorRevisions, or Include. A Unit that has merged past the ChangeOrder's start is an error whatever this says. Refused with an Insert, Upsert, or TransformPaths ChangeOrder, whose Links read their sources as they are at its end rather than merging a range.
Protect boolean Record the paths each Unit write changes as protected local overrides, so a later merge from upstream does not overwrite them. By default a write claims nothing and each path keeps the protection it already had. Accepted only for an Invoke ChangeOrder and for one that follows Insert, Upsert, or TransformPaths Links: refused for a promotion that merges, which protection holds paths against.
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.
Subgroup string A category recorded on the Mutations of each Unit write. Alphanumeric, at most 64 characters, and not starting with ConfigHub.
TagID string (uuid) A Tag to put on the Revision each Unit the promotion writes is left at, clones included. Units the promotion leaves Unchanged are not tagged. Requires Use permission on the Tag, and cannot be used with ChangeOrderID, whose own Tags mark what it promotes. A selected Space with a Unit to write that the Tag already marks fails, and nothing in it is written.
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.
Error Set when the gates refused the promotion: why, with each failed gate's message among its Details.
Final Array of PromoteGateResult When Complete, the gates of the ChangeWorkflow's Final, evaluated over each Space of the last Stage. The ChangeOrder's Stage becomes Completed once they all hold.
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

The body of an error response: the error as data (Error), and as one string (message) for clients written before Error.

Properties

Property Type Required Description
Error The error: its message, category (Type), HTTP status, details, and structured items.
message string The error as one string: its message, with any details, items, and individual errors appended. Kept for clients written before Error; new clients read Error.