Skip to main content
A deployment group connects firmware to the devices that should run it. It holds the targeting rules — which devices are in scope — and a sequence of releases, each shipping one firmware build. When a device checks in, NervesHub evaluates every active group against that device’s tags and firmware version, and a match earns an update notification.
The web console calls these deployment groups, while the REST API and the nh CLI still use deployment / deployments in their paths and command names. They are the same object.
1

Upload firmware

Before creating a group, you need a firmware UUID. If you have not yet uploaded your firmware, do so now:
The command prints the UUID of the uploaded firmware. Copy it — you will use it in the next step. If you are working with firmware that is already uploaded, retrieve its UUID with:
2

Create a deployment group

Create a group that targets devices carrying a specific tag and running a qualifying firmware version:
Newly created groups are inactive by default. No devices will receive the update until you explicitly activate the group in the next step.
3

Activate the group

Turn the group on to begin delivering firmware to matching devices:
Once active, NervesHub notifies eligible devices the next time they check in. Devices that are already online receive the notification within seconds.
4

Monitor the rollout

Track progress using the list and show commands:
nh deployment show reports how many devices have been notified, how many have successfully applied the update, and how many are pending or have failed.

​
Targeting devices

A group targets on two conditions, and a device must satisfy both.

​
Tags

Tags are arbitrary strings you assign to devices — main, qa, beta, region-us-east. A group lists one or more, plus a tag operator deciding how they combine: So a group listing beta and region-us-east targets only devices carrying both under Require all, and every device carrying either under Allow any.

​
Version condition

The group also filters on the firmware version a device is currently running — a semver expression such as >= 1.0.0, ~> 1.2, or < 2.0.0. Only devices satisfying it are eligible. Leave it empty to match on tags alone. Version conditions let you stage a migration: require devices to be on ~> 1.x before they can receive 2.0, so devices on unsupported older versions never pick up a breaking update.
A group also records the platform and architecture of the firmware it was created with, and every later release must match them. This stops firmware for one board being rolled out to a group full of another, so create a separate group per board rather than reusing one.

​
Releases

Firmware reaches a group through a release. Releases are numbered in the order they are created, each carries the firmware (and optional archive) being shipped plus an optional description and notes, and the group points at whichever is current. Because the history is kept, you can see exactly which firmware a group shipped and when.
A deployment group does not “finish”. It stays active indefinitely, waiting for devices that match its conditions — including devices you register months later.

​
Rollout safety controls

Each group carries limits that contain a bad release: A device that trips its failure thresholds goes into the penalty box and stops receiving update notifications until the timeout expires, which keeps one device stuck in a reboot loop from consuming rollout capacity. Clear it manually from the device page once you have addressed the cause.
Attaching a workflow supersedes two of these: each step paces itself with its own concurrent_updates, and the step order replaces the priority queue.

​
Shipping a new release

To deliver a new firmware version through an existing group, update its firmware reference — this creates a new release:
Devices are evaluated against the new release on their next check-in. You can update the version condition or target tag the same way:

​
Deactivating a group

Stop delivering updates to new devices without deleting the group:
This is the fastest lever during an incident. Devices that have already applied the update are unaffected, but no further devices receive it until you reactivate.
Deactivating does not roll back devices that already applied the firmware.

​
One-step upload and ship

For CI/CD pipelines where the latest firmware should go out immediately, use --deploy on the upload command:
This uploads the firmware, creates a release on the named group, and activates it in one command. The group must already exist; --deploy does not create one.

​
Staging a rollout

Everything above updates every matching device at the same pace. To roll out in stages instead — a small canary batch, a sign-off, then the rest — attach a workflow.

Deployment Group Workflows

Define the stages of a rollout in a JSON file, with per-step targeting, concurrency, failure tolerance, and approval gates.