# Update a rolling group

Source: https://www.jawsdeploy.net/rest-api/rolling-group-update | Section: Rolling Groups

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

`PUT /api/project/rolling-group`

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](https://www.jawsdeploy.net/rest-api/project-step-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

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `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 | array<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. |
| `onNoTargets` | body | string | no | What happens when no machine matches any step in the group. `Skip` (default), `Warn` or `Fail`. A deployment started for other machines only always skips. |

### 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`
- `onNoTargets` - `Skip`, `Warn`, `Fail`

## Response fields

| 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. |
| `onNoTargets` | string (enum) | `Skip`, `Warn` or `Fail` - what the group does when no machine matches any of its steps. |
| `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 | `rollingGroupId` is missing, unknown, or belongs to another project - `invalid rolling group ID`. |
| 400 | An unrecognised `machineOrder`, `onMachineFailure`, `onMemberFailure` or `onNoTargets` 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. |

Example request:

```
PUT /api/project/rolling-group HTTP/1.1
Authorization: Basic <base64(serviceAccountId:apiKey)>
Content-Type: application/json

{
  "projectId": "prj_42",
  "rollingGroupId": "rg_7a1",
  "windowSize": 2,
  "onMachineFailure": "ContinueToOtherMachines"
}
```

Example response:

```
{
  "rollingGroupId": "rg_7a1",
  "projectId": "prj_42",
  "name": "web rollout",
  "order": 3,
  "windowSize": 2,
  "machineOrder": "TagPriority",
  "machineOrderTagIds": ["tag-canary"],
  "waitBetweenMachineGroups": true,
  "onMachineFailure": "ContinueToOtherMachines",
  "onMemberFailure": "SkipRestOnThisMachine",
  "onNoTargets": "Skip",
  "memberStepIds": ["step-1", "step-2", "step-3", "step-4"]
}
```