Rolling deployments

How many machines a step touches at once has always been configurable, and defaults to one at a time. What you could not say before is anything about which machine goes first, when to stop, or how much of the deployment one machine should finish before the next begins.

That is the gap rolling deployments fill. Deploying one machine at a time is not a rollout if the order is arbitrary, if a failure on the first machine does not stop the second, and if each step still sweeps the whole fleet before the next one starts.

This guide covers five tasks. Start with the first if you are deploying anything that serves traffic.

Where these settings live

Everything below is on a project's Steps tab. There is no feature switch to turn on: a step already has a window and a machine order, and you change them. A rolling group is created by turning an existing step into one, then moving its neighbours in.

In the step list a group is drawn as a header row with its members indented underneath, carrying a step count and a caret to collapse it. Dragging moves whole blocks - an ungrouped step, or a group with all its members - so a drag can never split a group.

1. Run several steps per machine before moving on

Your deployment is the usual four actions and the fleet still goes down. Put the four steps in a rolling group.

1. Make sure the four steps sit next to each other in the step list, with nothing in between.
2. On the first step, open Step actions and choose New rolling group from this step.
3. On each of the other three, open Step actions and choose Move into '...', naming the group you just made. The option only appears on steps that can legally join it.
4. Click the group's header row to open its settings, and give it a name under Rolling group. The name appears in the step list, the deployment preview and the logs.
5. Leave Window size at its default of 1. That is one machine out of service at a time.
6. Save group.

Rules the editor enforces

• Members must be consecutive, with no non-member step in between. If one is in the way, the group is rejected and the message names it.
• Every member's Run on must be target machines. A group works by moving from machine to machine, so a step that runs on a worker or drives cloud targets has no machines to roll across and cannot join.
• Groups do not nest, and a group holds at least one step.

What the group takes over

Once a step is a member, the group owns the window, the machine order, the order tags, the barrier, and when this step fails on one machine. The step's Rollout card is replaced by a note naming the group and showing the settings actually in force. Those stored values are not erased - they apply again if the step leaves.

Each member keeps its own machine filters, its own when this step fails, its own run after stop, and its own execute condition, evaluated per machine.

2. Roll out one machine at a time

The deployment is a single action - deploy the package, restart the service - and you want to control how many machines it touches at a time. You do not need a group for this.

Open the step and go to the Rollout card. Set the window, labelled Parallel execution - maximum number of machines, to 1. It is already the default, so confirm it rather than assume it. Leave Deploy to machines in this order on Machine name for a stable, predictable order.

Raise the window to move a few machines at a time instead. It is capped by your organization's maxParallelMachines setting, which defaults to 8; a window above the cap is rejected.

The window controls how many machines one step touches at a time. It does not change that the step finishes on every machine before the next step starts. If the deployment is more than one action, task 1 is the answer.

3. Deploy to a canary first

You want one machine to take the release first and prove it before the rest of the fleet follows.

1. Tag your canary machine, for example canary.
2. Open the group's settings from its header row - or the step's Rollout card, for a single rolling step.
3. Set Deploy to machines in this order to Tag priority.
4. In the tag list it reveals, put canary first, then any further tags in the order you want them.
5. Tick Wait between machine groups, the barrier.

A machine's rank is the index of the first tag it carries. Machines run in rank order, and by machine name within a rank, so the order is stable between deployments. Machines carrying none of the tags run last - they are not excluded, since excluding machines is still the job of the machine filter. If the tag list ends up empty, the order falls back to machine name rather than an arbitrary one.

With the barrier on, every machine of one tag rank finishes before the next rank starts, so the canary goes alone all the way through the group.

On a single step the Rolling deployment tick box does steps 3 and 5 in one click; you still pick the tags. Unticking keeps your tag list, so re-ticking restores the choice. A group's panel has the same two controls but no such preset.

Running a smoke test only on the canary

Give the smoke-test member a machine tag filter of canary and leave the other members unfiltered. A group's machine set is the union of the machines its members target, and on each machine only the members that target it run. Every machine enters the rollout and runs the other members; only the canary runs the smoke test, and on the rest that column reads not targeted.

Grouping never widens a step's reach. A step targets exactly the machines it would have targeted on its own, environment scoping is untouched, and deployment-level machine include/exclude still applies ahead of everything else.

4. Stop the rollout when a machine fails

A machine fails part-way through and you do not want the rollout to carry on. Three settings answer three different questions, evaluated inside out. Getting the right one is the difference between stopping the rollout and stopping the deployment.

Walk it through. A member fails on web01. The first setting decides what happens on web01 itself. web01 is now a failed machine, so the second decides whether web02 starts. The third, set on the member that failed, decides whether the steps after the group run.

The most common mistake. Both group settings are about the rollout - which machines, and which of the group's steps, still run. Neither stops the deployment. To stop the deployment, open the member itself and set When this step fails to Stop the deployment. The step editor says so on every member.

On a single rolling step the equivalents are both on that step's Failure card: When this step fails on one machine (Carry on with the other machines by default, or Stop, do not start any more machines) and When this step fails (Continue to the next step by default, or Stop the deployment).

Rules that hold whatever you set

• Cancellation always wins. A cancelled deployment stops between members, not just between steps.
• Stopping never kills work in flight. It stops new machines and steps from starting; whatever is already running finishes.
• Run after stop steps still run, members inside a group included. That is where cleanup and notification belong.
• A failure is an Error-level log line, which raises the step's error count - and that count, not the status, is what every failure policy reads.

5. Change a rollout setting and have it take effect

You changed the group's window size, redeployed, and the deployment ran the old value.

A release is a snapshot. When you create one, the group and all its settings are copied into the release alongside the steps, and each release step's membership is rewritten to point at the snapshotted group. Editing the project afterwards does not change what an existing release deploys.

So: change the setting on the project, create a new release, and deploy that. Redeploying an existing release deploys the settings that release was snapshotted with.

What you see while it runs

The deployment preview shows the resolved machine order, the window, the barrier, and for a group a machine-by-machine list of exactly which steps will run where. The log tree runs Group to Machine to Step, with machine nodes created up front in resolved order and starting as queued, so machines not yet reached are visibly waiting rather than missing. A rollout order line names the machines in the order they will run and why that order was chosen.

Driving it from the API

Every setting in this guide is also reachable over the REST API and from MCP clients. See List rolling groups, Create a rolling group, Update a rolling group, Dissolve a rolling group and Move a step in or out of a rolling group.

Related reading: Project Steps Explained for how steps target machines in the first place, and Projects and Deployment Logic for where the deployment process sits.