Setup experience: scope software via labels

[marko-lisica]

Goal

User story
As an IT admin,
I want to install software (Fleet-maintained apps, App Store apps, or custom packages) during new host setup only on hosts that are a member of the specific label
so that I can scope software install more granularly (e.g. by department, role, hardware, etc. OR to scope a stable version to new hosts.

Changes

Software's labels (scope) should be respected in setup experience for all supported platforms.

When a host enrolls, enqueueSetupExperienceItems selects every item flagged install_during_setup for the host's team and platform with no label filtering, so out-of-scope software is installed on and shown to the enrolling host. This story adds per-host label-scope filtering at enrollment, reusing the scope logic that already gates the normal install paths. Multi-platform setup experience, multiple packages per title, and the tabbed Install software UI already shipped, so label scope is the remaining gap.

More details in Figma

Product

• UI changes: Figma. The tabbed Install software UI already shipped; the dev notes (remove help text, Versions tooltip copy, first-added tooltip) appear delivered by Fleet UI: Multi-package secondary UI — policy automation, setup experience, install-details hash #49079 and are verified in QA (Setup experience labels: documentation and engineering QA #49407).
• CLI (fleetctl) usage changes: No changes
• YAML changes: Re-apply the setup_experience note reverted by Revert docs changes for #24989 (Setup experience: scope software via labels when Macs boot) #27119, updated for all platforms + label scope. Tracked in Setup experience labels: documentation and engineering QA #49407.
• REST API changes: No changes. Setup experience selection is team-level and host-independent; scope filtering happens at enrollment.
• Fleet's agent (fleetd) changes: No changes
• Fleet server configuration changes: No changes
• Exposed, public API endpoint changes: No changes
• fleetdm.com changes: No changes
• GitOps mode UI changes: No changes
• GitOps generation changes: No changes
• Activity changes: No changes
• Permissions changes: No changes
• Changes to paid features or tiers: No changes. Custom packages and VPP are already Fleet Premium.
• My device and fleetdm.com/better changes: No changes
• Usage statistics: No changes
• Other reference documentation changes: articles/macos-setup-experience.md. Tracked in Setup experience labels: documentation and engineering QA #49407.
• First draft of test plan added

Engineering

• Test plan is finalized
• Contributor API changes: No changes.
• Feature guide changes: articles/macos-setup-experience.md — note that setup experience respects label scope. Tracked in Setup experience labels: documentation and engineering QA #49407.
• Database schema migrations: No changes. software_installer_labels, vpp_app_team_labels, and label_membership already exist.
• Load testing: Not required. The enqueue query gains an EXISTS scope predicate per software union part, run once per host at enrollment; same order as the existing per-item scope checks on the normal install path.
• Pre-QA load test: Not required.
• Load testing/osquery-perf improvements: None.
• This is a premium only feature: Yes. Scope tables and setup experience are already premium-gated; no new tier gating.

Risk assessment

• Requires testing in a hosted environment: No. Local dev with hosts on each platform is sufficient.
• Requires load testing: No.
• Risk level: Low
• Regression watch: no-label software must still install on every host; exclude-any must honor the label_updated_at vs label created_at timing for dynamic labels; the first-added dedup must select the first-added in-scope package per title.

Test plan

Make sure to go through the list and consider all events that might be related to this story, so we catch edge cases earlier.

Core flow

• Mark software for setup experience with an include-any label. Enroll an in-scope host and an out-of-scope host. Confirm only the in-scope host installs it and shows it in setup progress.
• Repeat with an exclude-any label.
• Repeat with an include-all label.
• Confirm software with no labels still installs on every host.

Platforms

• macOS (Apple MDM / DEP).
• Windows and Linux (Orbit enrollment).
• iOS or iPadOS (VPP app).

GitOps

• Set setup_experience: true on a label-scoped software item, run fleetctl gitops, enroll a host, and confirm scope is respected.

Edge cases

• Two in-scope packages for one title: only the first-added installs.
• First-added package out of scope, a later one in scope: the later one installs.
• Host re-enrollment (failed-step reset) still applies scope and skips already-succeeded items.

Permissions

• Setup experience configuration is premium; confirm no per-role behavior change.

Testing notes

Android is out of scope: it does not use the setup experience enqueue flow (software is baked into the Android policy at enroll).

Confirmation

1. Engineer: Added comment to user story confirming successful completion of test plan.
2. QA: Added comment to user story confirming successful completion of test plan.
3. QA: Determined whether this story needs Playwright automation.
   • Needs automation: Yes / No
   • If yes, filed a follow-up issue in the :help-qa project with status "Needs automation":