From 773c162a5010992f93f03d26d1e134fe4d459de6 Mon Sep 17 00:00:00 2001
From: Mitch Francese <2227948+tux234@users.noreply.github.com>
Date: Fri, 31 Jul 2026 12:10:33 -0400
Subject: [PATCH] Configuration profiles guide: document label scoping (#49494)
## Summary
- Adds a **Target hosts with labels** section to the Configuration
profiles guide (`articles/custom-os-settings.md`).
- Documents the three targeting modes (**Include all**, **Include any**,
**Exclude any**), that only one can be used per profile, and that
profiles are inherently platform-scoped (no label needed to keep a
profile on the right platform).
- Shows the flow across Fleet UI, GitOps (`labels_include_all` /
`labels_include_any` / `labels_exclude_any`, with a YAML example), and
the Fleet API.
- Bumps `publishedOn` to the current date. Author unchanged.
## Why
Prospects and customers hit this gap when trying to scope a profile to a
subset of hosts: the label include/exclude syntax lived only in the YAML
and REST API reference docs, with no walkthrough in the guide.
## Test plan
- [ ] Article renders correctly on the fleetdm.com preview
- [ ] All links resolve
- [ ] Meta tags present with updated `publishedOn` date
- [ ] Style guide compliance verified
---
articles/custom-os-settings.md | 30 +++++++++++++++++++++++++++++-
1 file changed, 29 insertions(+), 1 deletion(-)
diff --git a/articles/custom-os-settings.md b/articles/custom-os-settings.md
index b1afeb443a..ee9fa00852 100644
--- a/articles/custom-os-settings.md
+++ b/articles/custom-os-settings.md
@@ -26,6 +26,34 @@ Fleet UI:
Fleet API: Use the [Create configuration profile endpoint](https://fleetdm.com/docs/rest-api/rest-api#create-configuration-profile) in the Fleet API.
+### Target hosts with labels
+
+A configuration profile only applies to hosts on the platform it's built for. A macOS, iOS, or iPadOS profile (`.mobileconfig` or `.json`) never installs on Windows or Android hosts, and a Windows profile (`.xml`) never installs on Apple hosts. You don't need a label to keep a profile on the right platform.
+
+On Fleet Premium, you can use labels to scope a profile to a subset of those hosts. There are three targeting modes, and you can use only one per profile:
+
+- **Include all:** the profile applies to hosts that have all of the selected labels.
+- **Include any:** the profile applies to hosts that have any of the selected labels.
+- **Exclude any:** the profile applies to hosts that have none of the selected labels.
+
+If you don't select any labels, the profile applies to all hosts that support its platform.
+
+Fleet UI: on the **Add profile** modal, select **Custom**, choose a targeting mode, and select one or more labels.
+
+GitOps: set `labels_include_all`, `labels_include_any`, or `labels_exclude_any` on the profile. Each takes a list of label names. See the [YAML reference](https://fleetdm.com/docs/configuration/yaml-files) for the full syntax.
+
+```yaml
+controls:
+ windows_settings:
+ configuration_profiles:
+ - paths: ../lib/windows/profiles/*.xml
+ labels_include_any:
+ - Engineering
+ - Design
+```
+
+Fleet API: pass the same fields to the [Create configuration profile endpoint](https://fleetdm.com/docs/rest-api/rest-api#create-configuration-profile).
+
### Removal behavior
When a configuration profile is removed from Fleet or a host changes teams, Fleet reverses the settings that were applied by the profile:
@@ -169,6 +197,6 @@ To manually remove unmanaged profiles, ask the end user to go to **System Settin
-
+