Update Rings

Update Rings let you stage patch deployments across your fleet by grouping devices into ordered rings with different deferral periods, approval policies, and deadlines. Instead of pushing every patch to every device on the same day, you can let a small pilot group receive patches first, observe the results, and then widen the rollout to the rest of your organization. This is the standard approach for managing Patch Tuesday updates and reduces the blast radius of a bad patch.

Rings are built on top of the patch policy system. Patches flow through rings in order: Ring 0 (Default) receives patches immediately, Ring 1 defers for a few days, Ring 2 defers longer, and so on. Each ring can auto-approve certain categories and severities, or require manual approval before patches are deployed.

Default ring is created automatically

The first time anyone lists update rings for an organization, Breeze automatically creates a Default ring at order 0 with no deferral period and manual approval required for all patches. You do not need to create it yourself. If the Default ring does not appear, verify that the user has organization-scoped access and that the correct organization is selected.

---

Key Concepts

Device-to-Ring Assignment

Devices are assigned to rings through the Configuration Policy system, not directly on the ring itself. To target devices for a ring:

1. Create a Configuration Policy (or use an existing one).
2. Add a feature link of type patch that points to the update ring.
3. Assign the configuration policy to one or more targets at any level of the hierarchy:
   • Device — assign specific individual devices
   • Device Group — assign all devices in a group
   • Site — assign all devices at a site
   • Organization — assign all devices in the organization
4. Breeze resolves the assignments and counts how many devices each ring covers. These counts are shown in the ring list.

Note

A single device can be covered by multiple configuration policies. If a device matches assignments for more than one ring, the ring with the lowest ringOrder takes priority.

Ring Configuration Fields

Field	Type	Default	Description
Name	string	—	Human-readable name (e.g., “Pilot”, “Early Adopters”, “Production”)
Description	string	null	Optional description of the ring’s purpose
Enabled	boolean	true	Whether the ring is active
Ring order	integer	0	Position in the deployment sequence (0 = first, higher = later)
Deferral period (days)	integer	0	Days to wait after a patch is released before it becomes eligible for this ring (0 — 365)
Deadline (days)	integer	null	Days after deferral ends by which the patch must be installed. Null means no deadline
Grace period (hours)	integer	4	Hours after deadline before the device is marked non-compliant (0 — 168)
Included categories	string[]	[]	Patch categories to include (empty means all categories)
Excluded categories	string[]	[]	Patch categories to explicitly exclude
Patch sources	enum[]	null	Patch sources to include: microsoft, apple, linux, third_party, custom
Category rules	object[]	[]	Per-category auto-approval and deferral override rules
Auto-approve settings	JSON	{}	Auto-approval configuration
Device targets	JSON	{}	Device targeting rules (device groups, tags, sites, etc.)

Patch Sources

Source	Description
microsoft	Windows Update, WSUS, Microsoft Defender definition updates
apple	macOS software updates and security patches
linux	Distribution package manager updates (apt, yum, dnf)
third_party	Third-party application patches (browsers, runtimes, productivity apps)
custom	Custom patches uploaded by administrators

Patch Severities

Severity	Description
critical	Actively exploited vulnerabilities or remote code execution
important	Privilege escalation, denial of service, or significant security fixes
moderate	Defense-in-depth fixes or moderate-impact vulnerabilities
low	Minor fixes or informational updates
unknown	Severity not classified by the vendor

Approval Statuses

Status	Description
pending	Patch has not been reviewed for this ring
approved	Patch is approved for deployment in this ring
rejected	Patch is explicitly blocked from deployment in this ring
deferred	Patch is deferred to a later date with a deferUntil timestamp

---

Setting Up Update Rings

1. Verify the Default ring exists. Navigate to Patching > Update Rings. The Default ring is created automatically on first access (see the note at the top of this page).

2. Click Create Ring. Enter a name (e.g., “Pilot”), ring order, and configure the deferral period, grace period, and deadline for the ring.

3. Repeat for additional rings. Create an “Early Adopters” ring with a 3-day deferral and a “Production” ring with a 7-day deferral. Set ring order values to control the deployment sequence.

4. Configure device targets. Assign device groups, tags, or sites to each ring so the platform knows which devices belong to which ring.

5. Save. Each ring is now active and will control patch rollout velocity for its assigned devices.

API examples

Create a Pilot ring:

curl -X POST /api/v1/update-rings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pilot",
    "description": "IT team devices — receive patches immediately",
    "ringOrder": 0,
    "deferralDays": 0,
    "deadlineDays": 7,
    "gracePeriodHours": 4,
    "categoryRules": [
      {
        "category": "Security Updates",
        "autoApprove": true,
        "autoApproveSeverities": ["critical", "important"]
      }
    ]
  }'

Create an Early Adopters ring:

curl -X POST /api/v1/update-rings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Early Adopters",
    "description": "Power users — 3-day deferral after Pilot",
    "ringOrder": 1,
    "deferralDays": 3,
    "deadlineDays": 14,
    "gracePeriodHours": 8
  }'

Create a Production ring:

curl -X POST /api/v1/update-rings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "description": "General fleet — 7-day deferral after Pilot",
    "ringOrder": 2,
    "deferralDays": 7,
    "deadlineDays": 30,
    "gracePeriodHours": 4
  }'

Note

Rings are sorted by ringOrder first, then by createdAt as a tiebreaker. The Default ring always has ringOrder: 0. Customize ring ordering by setting different ringOrder values for each ring.

---

Category Rules

Category rules let you set per-category auto-approval behavior within a ring. This is useful for automatically approving critical security updates while requiring manual review for feature updates.

Caution

Category matching is case-sensitive. The category string in a rule must exactly match the category name reported by the vendor (e.g., "Security Updates", not "security updates"). If auto-approval rules are not triggering, check the exact capitalization of the patch category on the vendor side.

{
  "categoryRules": [
    {
      "category": "Security Updates",
      "autoApprove": true,
      "autoApproveSeverities": ["critical", "important"]
    },
    {
      "category": "Feature Packs",
      "autoApprove": false,
      "deferralDaysOverride": 14
    },
    {
      "category": "Definition Updates",
      "autoApprove": true
    }
  ]
}

Field	Type	Description
category	string	The patch category name to match
autoApprove	boolean	Whether matching patches are auto-approved
autoApproveSeverities	string[]	If set, only auto-approve patches with these severities
deferralDaysOverride	integer or null	Override the ring’s default deferral for this category

---

Ring Compliance

Each ring provides a compliance summary showing how many approved patches have been successfully installed across the organization’s devices.

curl /api/v1/update-rings/:id/compliance \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "data": {
    "ringId": "uuid",
    "ringName": "Production",
    "summary": {
      "total": 4500,
      "pending": 200,
      "installed": 4100,
      "failed": 50,
      "missing": 100,
      "skipped": 50
    },
    "compliancePercent": 91,
    "approvedPatches": 45,
    "totalDevices": 100
  }
}

Device Patch Statuses

Status	Description
pending	Patch is approved but not yet attempted on this device
installed	Patch was successfully installed
failed	Installation was attempted but failed
skipped	Patch was skipped (not applicable or superseded)
missing	Patch is required but has not been detected as installed

Compliance percentage is calculated as: installed / total * 100.

Note

A ring with zero approved patches reports 100% compliance. This is intentional — if there are no patches to install, there is nothing to be non-compliant about. Similarly, a ring with no devices in scope reports 100%. Once you approve patches and assign devices, the compliance percentage reflects actual installation status.

---

Ring Detail and Job History

curl /api/v1/update-rings/:id \
  -H "Authorization: Bearer $TOKEN"

The detail endpoint returns the full ring configuration plus:

• Approval summary — counts of patches in each approval status (pending, approved, rejected, deferred)
• Recent jobs — the five most recent patch deployment jobs for this ring, including status, device counts, and timestamps

Patch Job Statuses

Status	Description
scheduled	Job is queued for execution
running	Job is actively deploying patches
completed	All targeted devices have been processed
failed	Job encountered an unrecoverable error
cancelled	Job was manually cancelled

---

Viewing Ring Patches

List all patches with their ring-scoped approval status:

curl "/api/v1/update-rings/:id/patches?source=microsoft&severity=critical&page=1&limit=50" \
  -H "Authorization: Bearer $TOKEN"

Filters: source, severity, page, limit.

Each patch in the response includes an approvalStatus field showing its status within this specific ring (defaulting to pending if no explicit approval record exists).

---

API Reference

Method	Path	Description
GET	/api/v1/update-rings	List all enabled rings for the organization, sorted by ring order
POST	/api/v1/update-rings	Create a new update ring
GET	/api/v1/update-rings/:id	Get ring detail with approval summary and recent jobs
PATCH	/api/v1/update-rings/:id	Update ring configuration
DELETE	/api/v1/update-rings/:id	Soft-delete a ring (sets enabled: false)
GET	/api/v1/update-rings/:id/patches	List patches with ring-scoped approval status
GET	/api/v1/update-rings/:id/compliance	Get compliance summary for a ring

---

Troubleshooting

Ring order not respected Rings are sorted by ringOrder ascending, then createdAt ascending. If two rings have the same ringOrder, they are treated as peers. Assign distinct ringOrder values to enforce strict sequencing.

Patches stuck at “pending” in a ring Patches require explicit approval per ring. If auto-approval is not configured via categoryRules or autoApprove, patches remain in pending status until a user approves them. Check the ring’s approval summary for pending counts.

Deleting a ring does not remove patches Ring deletion is a soft delete — it sets enabled: false. The ring’s approval records and job history are preserved. Patches approved in other rings are unaffected.

Category rules not auto-approving Double-check that autoApproveSeverities includes the severity of the patches you expect to be auto-approved. See the case-sensitivity note in the Category Rules section above.