OS updates: update to latest after deadline (relative to OS release)

[noahtalerman]

Goal

User story
As an IT admin managing Apple (macOS, iOS, iPadOS) OS updates,
I want to set a deadline and have Fleet automatically update host's version to match the latest version
so that I can keep my hosts at the latest OS w/o having to bump the version myself.

Changes

Product

• UI changes: Figma
• CLI (fleetctl) usage changes:
  • If minimum_version is latest → require deadline_days, reject deadline
  • If minimum_version is a specific version → require deadline, reject deadline_days
• YAML changes:
  • [YAML] Revise update configurations for macOS, iOS, and iPadOS #50065
  • Use similar as existing errors for when value/field mismatch: deadline_date is required when minimum_version is set to latest
• REST API changes:
  • [API] minimum version settings for macos/iOS/iPadOS #50063
  • [API] Update OS update minimum version and deadline #50243
  • Use similar as existing errors for when value/field mismatch: deadline_date is required when minimum_version is set to latest
• 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: Disable options when GitOps mode enabled.
• GitOps generation changes: No changes
• Activity changes:
  • Global activities using existing type “OS updates: edited {platform}”
  • If latest selected, "actor updated macOS version to latest on hosts assigned to..."
• Permissions changes: No changes
• Changes to paid features or tiers: No changes
• My device and fleetdm.com/better changes: No changes
• Usage statistics: No changes
• Other reference documentation changes:
  • [Docs] Enhance OS update enforcement documentation for Apple #49676
  • [Docs] Fix link to available OS versions for Apple hosts #50245
• First draft of test plan added
• Once shipped, requester has been notified
• Once shipped, dogfooding issue has been filed

Engineering

• Test plan is finalized
• Contributor API changes: No changes
• Feature guide changes: See above
• Database schema migrations: See subtasks
• This is a premium only feature: Yes

ℹ️  Please read this issue carefully and understand it. Pay special attention to UI wireframes, especially "dev notes".

QA

Risk assessment

• Risk level: Low

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

Platforms to test across: macOS, iOS, iPadOS

MDM

• Add enforcement OS updates:
  • Custom version (existing behavior)
  • Latest version with deadline_days
• Remove minimum version OS updates (clear enforcement)
• Switch between enforcement modes (e.g., Custom → Latest version (based on host hardware)->Off)
• Verify DDM declaration is resent when a new OS version is detected by GDMF cron
• Turn Apple MDM on/off while automatic enforcement is configured
• DEP enrollment with automatic enforcement active (verify update_new_hosts implicit behavior)
• For mac: Test on Apple Silicon mac, T2 intel mac and pre-t2 Intel mac if possible(This may not be possible and is OK). Validate that the backfill table sets the proper software update device identifier for the type of mac
• Ensure Update New Hosts to Latest still works as expected with or without the setting enabled

Fleet (Teams)

• Set automatic enforcement at team level
• Set different enforcement modes across teams
• Transfer host between teams with different enforcement policies. Verify correct target version applies
• Verify behavior works as expected on a team and on no-team/unassigned

Host

• Host already at or above target version: no enforcement prompt
• Offline host: enforcement applies when back online
• DEP-enrolled host with automatic enforcement.
  • What happens? Is the host forced to update during enrollment even with update new hosts to latest disabled? Doc below in Edge Cases

Config

• GDMF cron polling interval: verify new versions are detected within 24 hours.
• Activity feed shows entry when Fleet auto-updates the target version Note: confirmed with product no longer a requirement

Retries

• GDMF endpoint unavailable. Cron retries, doesn't clear existing enforcement
• Define max retry attempts / backoff for GDMF polling failures

Integrations

• Webhook fires when automatic enforcement updates the target version (if configured) Note: confirmed with product no longer a requirement

UI

• Verify that all UI changes specified in the Figma wireframes are correctly implemented
• Verify expected UI states (loading, empty, error states if applicable)
• Dropdown with long option names renders correctly at narrow widths
• Gap between elements (target options and "user experience" should be 24px/1.5rem)
• "Days after release" input + tooltip renders cleanly
• Forms:
  • Error states: submit with invalid combos (latest + deadline, semver + deadline_days, deadline_days = (0, negative))
  • Disabled states: fields that should hide/disable based on dropdown selection (e.g., version input hidden in Latest mode)
  • Dynamic views: dropdown selection shows/hides correct fields (date vs. days input)

API

• Test all API endpoints added or modified in the API changes section of this issue
• Verify any new API endpoints appear in the list when adding an API-only user. The API endpoints display name, method, and path is the same as listed in the API reference docs
• Verify error handling for invalid inputs where applicable

GitOps (generate + run)

• Configure the feature through the UI and run fleetctl generate-gitops
• Confirm the generated .yml includes the expected fields (compare with YAML changes in the Product section)
• Modify the generated .yml and run fleetctl gitops
• Confirm the configuration updates correctly in Fleet
• Enable GitOps mode and verify the feature behaves correctly
• Apply YAML with minimum_version: "latest" + deadline_days: 14. This succeeds.
• Apply YAML with minimum_version: "latest" + deadline: "2025-07-01". This fails with clear error.
• Apply YAML with no minimum_version. This clears enforcement
• Backward compat: existing YAML with semver + deadline still works unchanged

Permissions

• Verify role restrictions are applied correctly for global roles
• Verify role restrictions are applied correctly for fleet-level roles
• Premium vs. Free: automatic enforcement options return clear error on Fleet Free
• Global Admin can set all enforcement modes
• Team Admin can set enforcement modes for their team
• Observer/Observer+ cannot modify OS update settings
• API-only user can set enforcement via API

Edge cases

• Host does not support target version: Confirm Fleet doesn't nag or report failure
• TargetVersion is not one in the provided list by Apple (see https://fleetdm.slack.com/archives/C03C41L5YEL/p1780339719927589)

Supplemental testing

Testing notes

Confirmation

1. Engineer: Added comment to user story confirming successful completion of test plan (include any special setup, test data, or configuration used during development/testing if applicable).
2. QA: Added comment to user story confirming successful completion of test plan.
3. QA: Determined whether this story needs Playwright automation.
   • Needs automation: No -> full OS upgrade (major/minor) would be expensive at the moment

[georgekarrv]

I can see this being a small, there will be a small frontend field, one new team setting, a table to store first seen release values and a cron to parse the versions available from gdmf https://gdmf.apple.com/v2/pmv.

We may even want an activity that 'fleet updated minimum version based on deadline' so it may even be a S + XXS but I will put small for now