Description
Creates a rolling group from a set of member steps. The members are given here rather than added one at a time, because a group with no members cannot exist.
Read List project steps first. Contiguity and the target-machine rule are properties of the whole ordered step list, so both are checked against it: the steps must be consecutive in order with no non-member between them, and every one must have a runOn of TargetMachine. If a step is in the way, reorder with Reorder project steps first.
Everything after memberStepIds is optional. Note the two group defaults that differ from the step equivalents: onMachineFailure is StopStep, and windowSize is 1 - a group exists to take machines out of service one at a time.
Settings live in the release snapshot. A group created after a release was cut does not apply to that release; create a new one.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId |
body | string | yes | The project the group belongs to. |
name |
body | string | no | Display name, shown in the step list, deployment preview and logs. Trimmed; maximum 500 characters. Blank or omitted becomes Rolling group. |
memberStepIds |
body | string[] | yes | The steps to group, in step order. Must be a consecutive run, and every step must run on target machines. |
windowSize |
body | integer | no | How many machines work through the group at once. Defaults to 1. Capped by the organization's maxParallelMachines, which defaults to 8. |
machineOrder |
body | string | no | MachineName (default) or TagPriority. |
machineOrderTagIds |
body | string[] | no | Ordered tag ids. A machine's rank is the index of the first of these tags it carries. Required when machineOrder is TagPriority. |
waitBetweenMachineGroups |
body | boolean | no | The barrier: finish every machine of one tag rank before the next rank starts. Requires machineOrder of TagPriority. |
onMachineFailure |
body | string | no | Whether the next machine starts after one fails. StopStep (default) or ContinueToOtherMachines. |
onMemberFailure |
body | string | no | Whether a machine runs the group's remaining steps after one fails on it. SkipRestOnThisMachine (default) or ContinueMembers. |
Enumerated values
Policy and order fields are sent and returned as names, not numbers. Parsing is case-insensitive; responses use the canonical casing. An unrecognised name is rejected rather than silently defaulted.
machineOrder-MachineName,TagPriorityonMachineFailure-ContinueToOtherMachines,StopSteponMemberFailure-SkipRestOnThisMachine,ContinueMembers
Response
| Field | Type | Description |
|---|---|---|
rollingGroupId |
string | The group's id. Pass this as rollingGroupId when updating, dissolving, or moving a step into the group. |
projectId |
string | The project the group belongs to. |
name |
string | Display name, shown in the step list, the deployment preview and the logs. |
order |
integer | Where the group sits among the project's steps. Derived from the order of its first member and never accepted from the caller, so it cannot disagree with the step list. |
windowSize |
integer | How many machines work through the group at once. 1 means a strict one-at-a-time rollout. Never above the organization's maxParallelMachines, which defaults to 8. |
machineOrder |
string (enum) | The order machines enter the group. One of MachineName - alphabetical, case-insensitive - or TagPriority, where a machine's rank is the index of the first tag it carries from machineOrderTagIds. Within a rank machines are ordered by name; machines carrying none of the tags run last. |
machineOrderTagIds |
string[] | Tag ids in priority order, first tag highest. Empty array when machineOrder is MachineName - the list is not persisted for an order that does not use it. |
waitBetweenMachineGroups |
boolean | The barrier. true finishes every machine of one tag rank before the next rank starts. Only ever true alongside machineOrder of TagPriority. |
onMachineFailure |
string (enum) | Whether the next machine starts after the group fails on one. StopStep - the default - starts no further machine; ContinueToOtherMachines carries on. Neither stops the deployment; that is onStepFailure on the member itself. |
onMemberFailure |
string (enum) | Whether a machine runs the group's remaining steps after one fails on it. SkipRestOnThisMachine - the default - skips them; ContinueMembers runs them, which is what a cleanup or notification member needs. |
memberStepIds |
string[] | The member steps, in step order. Projected from the steps' own rollingGroupId rather than stored on the group, so this and the step list cannot disagree. Always at least one id. |
Errors
| Status | Meaning |
|---|---|
400 |
memberStepIds was empty or omitted - a rolling group needs at least one member step. |
400 |
One or more of the steps to group were not found in this project. |
400 |
The members are not consecutive. The message names every step sitting between them. |
400 |
A member does not run on target machines - the message names the step and its runOn. |
400 |
An unrecognised machineOrder, onMachineFailure or onMemberFailure value. |
400 |
Validation failed: a window outside 1 to the organization maximum, a missing group name, TagPriority with no tags, or the barrier without TagPriority. |
401 |
Missing or invalid Basic auth credentials, or the service account may not edit this project. |