Managing Host Groups

Overview

Host groups are the primary way to organise your fleet in PatchMon. A group is a named bucket with a colour and an optional description. Each host can belong to any number of groups. Groups appear as a column and filter on the Hosts page, as a selector on the Patching page, as a scope for patch policies, and as a filter in the Integration API.

This page covers creating, editing, and deleting groups, assigning hosts to them, and how groups feed into other parts of PatchMon.

Permission required: can_manage_settings to create / edit / delete groups (the page sits under Settings); can_manage_hosts to change which groups a host belongs to.

Where to Find Host Groups

There are two places to manage groups in the UI, and both edit the same data:

• Settings → Host Groups: full management page with a table view, create / edit / delete actions, and host counts.
• Options page (/options): the same host-groups component, rendered inline for operators who have can_manage_hosts but not can_manage_settings.

You can get to host counts and host assignments from either place, but the Settings → Host Groups route is the canonical one and is the one this page describes.

Creating a Group

1. In the left navigation, open Settings.
2. Click Host Groups in the settings sub-menu. The page opens with a table listing existing groups and a Create Group button in the top right.
3. Click Create Group. A modal titled Create Host Group opens.

The form has three fields:

Click Create Group to save. The new group appears immediately in the table with a 0 hosts count.

Assigning Hosts to a Group

Groups are assigned on the host, not on the group. You have three paths:

During enrolment

On step 2 of the Add Host wizard (Host details) tick each group the host should belong to. See Adding a Host.

Inline from the Hosts page

1. Open Hosts from the left navigation.
2. Find the row for the host you want to change.
3. Click the value in the Group column. It becomes an editable multi-select with coloured group chips.
4. Tick / untick groups, then click away (or press Enter) to save.

Bulk assign

1. Open Hosts.
2. Select multiple rows using the checkboxes in the Select column.
3. A toolbar appears above the table with Fetch Reports, Assign to Group, and Delete.
4. Click Assign to Group. A modal lists every group with a checkbox.
5. Tick one or more groups and click Assign to Groups. All selected hosts are updated in a single call.

Note on bulk behaviour: the bulk assign modal sets the selected groups on each host. It does not add to existing memberships. If you want to add a group without removing others, use the inline edit on the Hosts table or the Host Groups selector on the Host Detail page.

From the Host Detail page

Open any host (Hosts → click friendly name). On the Host Info tab, the Host Groups field is a multi-select identical to the one on the Hosts list. Tick / untick and click away to save.

Editing a Group

From Settings → Host Groups:

1. Click the pencil icon in the Actions column of the group you want to change.
2. A modal titled Edit Host Group opens with the current Name, Description, and Color pre-filled.
3. Change whatever you need and click Update Group.

Editing a group's name or colour updates it everywhere: the Hosts table, the host's detail page, the Patching targets, and the API all pick up the new value immediately.

Deleting a Group

Deletion is restricted to prevent you from orphaning hosts by accident.

1. From Settings → Host Groups, click the trash icon next to a group.
2. The Delete Host Group modal opens.
3. If the group has no hosts, the Delete Group button is enabled. Confirm to delete.
4. If the group has one or more hosts, the modal shows a yellow warning with the list of hosts in the group, and the Delete Group button stays disabled.

What happens to hosts when the group is deleted?

You cannot delete a group that still contains hosts. The UI prevents it and the server returns an error. To delete a populated group, first move or remove the hosts:

• Move each host out of the group: open the host, untick the group in the Host Groups field, and save. The host stays in PatchMon and keeps any other group memberships.
• Or use bulk-assign from the Hosts page to reassign many hosts at once.

Once the group is empty, return to Settings → Host Groups and delete it.

Note: Deleting a group does not delete hosts. Hosts that were only in that group become ungrouped and still appear in the Hosts list. They can be reassigned to another group later.

Filtering by Group

On the Hosts page

1. Click Filters in the Hosts toolbar to reveal the filter panel.
2. Open the Host Group dropdown. It lists every group plus an Ungrouped option.
3. Pick a group. The table reloads showing only hosts in that group.
4. Use Clear Filters to reset.

You can also deep-link by visiting /hosts?group=<groupId>; group-clicks from other parts of the UI (for example the Host Groups page's host count badge) do exactly this.

Grouping the table

Above the filter panel, the No Grouping dropdown lets you group rows by Group, Status, or OS. Picking By Group splits the Hosts table into sections, one per group, each with a count header. Hosts in multiple groups appear under each of their groups. This is a visual grouping, not a filter.

Hiding stale hosts

The Hide Stale toggle on the Hosts toolbar can be combined with a group filter to narrow a view down to "active hosts in the production group", for example.

How Groups Feed Other Features

Groups are a selector across the product. Wherever a workflow asks "which hosts?" you can usually answer "this group".

Patching

• When you build a patch run, the target picker offers Host or Host group as the target type.
• Choosing a host group expands the target to every current member at the time the run is queued.
• Patch policies (recurring runs) can use a host group as the primary selector, so adding a new host to the group automatically includes it in the next scheduled run.

For the full patching flow, see the Patching chapter.

Integration API

The Integration API exposes host-group membership as a filter on host-related endpoints. Common patterns:

• Listing hosts in a specific group.
• Fetching package status rolled up by group for an external dashboard.
• Triggering bulk reports only for hosts in Production.

See Integration API Documentation for the exact endpoints and parameters.

Alerts and Reporting

Some alert channels and scheduled reports support scoping by host group so that, for example, the platform team only receives notifications for Production hosts while the dev team owns Staging. See the Alerts & Notifications chapter for specifics.

Dashboards

Dashboard cards and the Hosts summary counts are fleet-wide by default. Individual host-centric views (Host Detail) show the groups a host belongs to as coloured chips, and clicking a chip deep-links back to a group-filtered Hosts list.

Good Practice

A few patterns worth knowing:

• Keep group names short. They show up in chips, tables, and filter dropdowns with limited width.
• One group per purpose. Environment (Production, Staging), role (Web, DB, Cache), location (EU-West, US-East), or owner (Platform, Billing) are all reasonable axes. Combine them by giving a host multiple memberships instead of creating compound groups like Prod-Web-EU.
• Use colour consistently. For example: red for production, yellow for staging, green for development. Consistent colours make the chips in the Hosts table and on dashboards readable at a glance.
• Empty is fine. Groups with zero hosts are valid; they are often created ahead of time for patch-policy planning. The UI just won't let you delete a group that still has hosts.

Related Pages

• Adding a Host: assign groups during enrolment.
• Host Detail Page: edit a single host's group memberships.
• Integration API Documentation: query hosts by group programmatically.