// Rolling Groups

Update a rolling group

Change a group's own settings. Membership is not changed here.

PUT/api/project/rolling-group

Description

Updates a rolling group's own settings. Only the fields you send are applied - an omitted field keeps its current value, and a blank name keeps the current name.

Membership is not changed here. Use Move a step in or out of a rolling group, which is the only path that re-checks the members are still consecutive. There is no memberStepIds on this request.

Settings changes require a new release. A release is a snapshot: changing a group's window and redeploying an existing release deploys the old window.

Parameters

NameInTypeRequiredDescription
projectId body string yes The project the group belongs to.
rollingGroupId body string yes The group to update. Must belong to this project.
name body string no New display name. Trimmed. Blank or omitted keeps the current name.
windowSize body integer no How many machines work through the group at once. Omitted leaves it unchanged.
machineOrder body string no MachineName or TagPriority. Omitted leaves it unchanged.
machineOrderTagIds body string[] no Ordered tag ids. Omitted leaves the current list unchanged.
waitBetweenMachineGroups body boolean no The barrier. Requires machineOrder of TagPriority. Omitted leaves it unchanged.
onMachineFailure body string no StopStep or ContinueToOtherMachines. Omitted leaves it unchanged.
onMemberFailure body string no SkipRestOnThisMachine or ContinueMembers. Omitted leaves it unchanged.

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, TagPriority
  • onMachineFailure - ContinueToOtherMachines, StopStep
  • onMemberFailure - SkipRestOnThisMachine, ContinueMembers

Response

FieldTypeDescription
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

StatusMeaning
400 rollingGroupId is missing, unknown, or belongs to another project - invalid rolling group ID.
400 An unrecognised machineOrder, onMachineFailure or onMemberFailure value.
400 Validation failed - the same rules as create.
401 Missing or invalid Basic auth credentials, or the service account may not edit this project.