Split the deployment group docs by task, not by difficulty

[joshk]

Two pages were both called Deployment Groups — one under Setup, one under Advanced — covering overlapping ground, both ending in CLI examples. Nothing told a reader which to open, which is why the quickstart link said "Deployment Groups" and landed on the conceptual page.

What changed

setup/deployments now carries everything needed to run a group. The steps it already had, plus the material that was stranded on the other page: targeting and the tag operator, version conditions, releases, and the safety-control table. One page, one job.

Workflows get their own page. They are a different kind of thing from "how deployment groups work" — a JSON file you author, upload, and validate, with approval gates and its own diagram. None of that lifecycle was documented anywhere.

concepts/deployments is removed and redirects to /setup/deployments, so the quickstart link now has an unambiguous target.

Advanced becomes PKI, Firmware Signing, and Workflows — all genuinely optional depth, which fits the label better than it did.

The workflows page

Built from the implementation rather than invented. It documents what was missing entirely:

• The file format — version, 1 to 6 steps, and every field a step takes
• Uploading — where it lives in the group's Settings, that it validates on upload, and that errors name the failing path, so steps/0 with name means the first step has no name
• The two mistakes that bite — every step needs a name, including approval_required and catch_all steps, and steps cannot be empty
• Approval steps — the Waiting on you banner, Approve and continue, and that approving records who and when
• That it is an early release feature, with the issue tracker link the UI itself points at

The example is test/fixtures/workflow-definition.json from the server repo — a four-step rollout that splits canaries by connection type, so a firmware that breaks cellular is caught on ten metered devices rather than the fleet. Better than anything invented for the purpose, and it is already covered by a test asserting it stays valid.

One correction

The old page listed concurrent_updates among the group's safety controls without mentioning that a workflow overrides it. The settings UI says otherwise:

A workflow paces each step separately, using the step's own concurrent_updates, so this limit is not applied while one is in use.

The same applies to the priority queue. Both are now stated on each page, with the boundary drawn: a workflow changes the order and pacing of a rollout, not what happens to a device that cannot take the update.

Also here

api/websocket-events had a broken #device-server-events anchor — Mintlify keeps the arrow when slugifying, so the real anchor is #device-→-server-events. It now links to #rebooting, the event the sentence is actually about. The fix already exists in #12, but that PR is blocked on the server-side spec fix, and this one would fail link-rot without it. #12 will need a rebase.

Checks

Schema valid. 36 navigation pages all resolving, zero broken internal links, zero broken anchors, and all four redirects have their source removed.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
NervesHub	🟢 Ready	View Preview	Sep 5, 2026, 8:01 AM

💡 Tip: Enable Automations to automatically generate PRs for you.