Skip to content
demonstration scripts on how to use the API to do staged releases to a fleet of devices.
Branch: master
Clone or download
thgreasi Merge pull request #26 from Actyx/mca/add-tag-values
Add tag values to
Latest commit 79dd6d6 May 14, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information. Update for clarity May 12, 2019
balena.env Change all resin references to balena Nov 19, 2018 Change all resin references to balena Nov 19, 2018 Change all the routes to v5 Feb 20, 2019 Change all the routes to v5 Feb 20, 2019 Change all the routes to v5 Feb 20, 2019 Change all the routes to v5 Feb 20, 2019 Change all the routes to v5 Feb 20, 2019 Change all the routes to v5 Feb 20, 2019 Update for clarity May 12, 2019

Staged Updates on balena

This repo is a collection of scripts to demonstrate some of the new API endpoints offered on balenaCloud to enable the more fine grained control of app updates across a fleet of devices. These scripts simply show how to use the available primitives and in the near future this functionality will be surfaced on the UI and via the CLI.

To use these scripts you need to edit the balena.env file adding the Application you want to operate on (replacing APP_ID with the appropriate value) and your authToken from the preferences page on the balenaCloud dashboard.

  • Note that while using resin.env is still supported, it is destined for deprecation and is discouraged.

At a basic level, these scripts allow one to disable the auto tracking on the App, so that the fleet no longer automatically updates every time you do a git push balena master. They also allow one to set a group of devices (marked with a device tag) to advance to a specific commit/build (selected from the releases list). Using the primitives shown in these scripts one could have a fleet of devices and deploy specific commits to specific subgroups as and when needed. It would be very easy to set up a system where developers have devices in the fleet set to local mode so they can test and develop locally, and when happy commit and merge the code into a branch that would then be released to the larger testing group. Obviously once the code being tested on the testing group is deemed stable, it would then be released to the whole fleet by advancing the fleet wide Application commit.


  1. a balenaCloud account
  2. your system should have jq and curl installed


  1. Ensure that balena.env is updated with the correct APP_ID and authToken
  2. To disable the automatic update tracking run:
  1. We can now set the whole fleet to a specific commit (something we decide is "stable" or "production") by running:

Note that you need to provide the full commit hash for this command. It should also be noted that any devices that join/provision into the fleet after this is set, will download and update this commit. To confirm that this has worked, check the top right of the device list page and you should see the Application commit: value has been set to the commit you passed it in the command.

  1. If we want to have a few devices that are part of a testing group, we can use the script:
  1. For convenience, we can define a device tag with TEST (or any other tag) as its key that is used to designate the devices that are part of the testing group. So any device in the fleet that has the TEST tag can then be set with a testing build. The script will set all the devices with this tag to a specific commit/build:

This will update all devices that have a tag with key <TAG_NAME> (default is TEST) and value <TAG_VALUE>. If <TAG_VALUE> is omitted, it will update all devices that have a tag with the corresponding key, regardless of its value.

Note: The hash must be the full commit hash. It may take a few seconds for the test devices to start updating to the correct version of the code.

Returning to rolling releases

If you want to return the fleet to keep tracking rolling releases and downloading updates whenever they are pushed, just run:


and push a new commit, or use to set the App commit to the latest.

In case that you want to restore tracking releases on devices that were configured using or, you will need run the respective commands with an empty commit hash (this will set the target commit to null). So for a specific device you will need to run:


For a test group of devices you will need to run:

You can’t perform that action at this time.