Improve this doc

Release policy

When managing a fleet, you may require devices to be running different releases. By default, fleets follow a rolling release policy where new releases are deployed to all devices in the fleet once successfully built. However, you can customize this behavior, so the fleet or individual devices remain on a fixed release, by utlizing release pinning.

You may define the fleet and device release policies via the balenaCloud dashboard or programmatically through the API or SDKs.

Note: It is currently not possible to specify the fleet or device release policy via the balena CLI.

Pin fleet to a release

In the fleets dashboard, there is a Release policy header. By default, this policy is set to track latest, which means that new releases are immediately deployed to all devices in the fleet when built. Expanding this Release policy dropdown menu displays all releases for the fleet, and you can select a specific release to pin the fleet to. When the fleet is pinned, all devices are updated to run the pinned release, and in the future, releases will not be deployed until the Release policy is updated to a newer release or set to track latest.

Pin fleet to release

Pin device to a release

As well as pinning a fleet to a specific release, you may pin individual devices to a specific release. By default, all devices track the fleet release. However, you may wish to run a different release on select devices, for example, a development device or when performing a canary deployment.

To do so, from the Device dashboard, select the device menu and choose Pin to release.

Pin device to release

Selecting Pin to release opens a modal window displaying a list of all successful releases from which you can select a specific release to pin the device to.

Pin to a specific device

Once the device has updated, it is shown to be on a Pinned release policy on the fleet dashboard rather than following the release policy of the fleet.

Device release policy

You can also pin multiple devices to a target release in the fleet dashboard by selecting them and choosing the Pin to release option from the Actions menu. Again this action opens a modal window allowing you to choose a specific release to pin the devices to.

Pin multiple devices

Using device tags, you can quickly select a group of devices and pin them all to a specific release by filtering by the device tag and choosing Pin to release from the Actions menu.

Using tags to pin multiple devices

Note: For more details about using the API to manage the release policy see the Fleet Management Masterclass.