Skip to content

[YAML] Patch policies: Notify end users before app updates #50678

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
marko-lisica wants to merge 3 commits into
base: docs-v4.92.0
Choose a base branch
from
Open

[YAML] Patch policies: Notify end users before app updates #50678

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
32ae648
[YAML] Patch policies: Notify end users before app updates
marko-lisica Aug 6, 2026
5e84182
update
marko-lisica Aug 11, 2026
713dc96
update
marko-lisica Aug 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 17 additions & 2 deletions docs/Configuration/yaml-files.md
View file
Open in desktop

@marko-lisica marko-lisica Aug 11, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dev note

  • If both patch_when_closed and notify_before_patching is set to true, throw an error:

Only one of "patch_when_closed" or notify_before_patching can be set to true,

  • If notify_before_patching is true on a policy (existing or being set in the same request) and the request explicitly sets continuous_automations_enabled to false, Fleet rejects the request instead of silently overriding it.
    • Applies to both create and update (API), and on fleetctl gitops (YAML). This only blocks an explicit false — omitting continuous_automations_enabled still auto sets it.

If "notify_before_patching" is true, "continuous_automations_enabled" can't be set to false.

  • If the user specifies, notify_before_patching on Windows Fleet-maintained app, throw an error:
    • Applies to API and GitOps

"notify_before_patching" is available for macOS Fleet-maintained apps. It's coming soon to Windows.

Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,15 @@ You can create a patch policy by setting `type` to `patch` and specifying `fleet

A patch policy's `query` automatically updates. Hosts will fail this policy if they’re not running the latest version found in [the app's metadata](https://github.com/fleetdm/fleet/tree/main/ee/maintained-apps/outputs). If `version` is set for `fleet_maintained_apps`, that version is included in the query.

To automatically install the app when this policy fails, you can add an automation by setting `install_software` to `true`.
To automatically patch the app when this policy fails, whether or not the app is open, set `install_software` to `true`.

To automatically patch the app when this policy fails and app is not open, set `patch_when_closed` to `true`.

To notify the end user before the app is patched, set `notify_before_patching` to `true`. Fleet shows a notification listing the apps that will be updated, waits 1 hour, then installs patch. A reminder is shown 5 minutes before the install. This option is only available on macOS, and requires Fleet Desktop app (available as Fleet-maintained app).

Fleet adds a read-only pre-install query that skips automatic install while the app is open and retries on the next policy run when `patch_when_closed` or `notify_before_patching` is set to `true`. Also, the `continuous_automations_enabled` is automatically set to `true` when one of these options is enabled..

Fleet-managed pre-install query is ignored for self-service, host details page, and setup experience installs.

#### Automations

Expand Down Expand Up @@ -203,6 +211,13 @@ policies:
fleet_maintained_app_slug: zoom/darwin
continuous_automations_enabled: true
install_software: true
- name: 1Password up to date
description: Outdated software might introduce security vulnerabilities or compatibility issues.
resolution: Install the latest version from self-service.
type: patch
fleet_maintained_app_slug: 1password/darwin
install_software: true
notify_before_patching: true
```

`default.yml` (for policies that neither install software nor run scripts), `fleets/fleet-name.yml`, or `fleet/unassigned.yml`
Expand Down Expand Up @@ -720,7 +735,7 @@ By default, Fleet-maintained apps will be updated to the latest version publishe
The fields below are all optional.

- `self_service` specifies whether end users can install from **Fleet Desktop > Self-service**.
- `pre_install_query.path` is the SQL query Fleet runs before installing the software. Software will be installed only if the [query returns results](https://fleetdm.com/tables).
- `pre_install_query.path` is the SQL query Fleet runs before installing the software. Software will be installed only if the [query returns results](https://fleetdm.com/tables). If a [patch policy](#patch-policy) has `patch_when_closed` or `notify_before_patching` set to `true`, Fleet manages this query and rejects this field.
- `post_install_script.path` is the script that, if supplied, Fleet will run on hosts after the software installs.
- `icon.path` is a relative path to the PNG icon that will be displayed in Fleet and on **Fleet Desktop > Self-service** instead of the default icon the icon sourced from Apple. It must be a square PNG with dimensions between 120x120 px and 1024x1024 px. Custom icons will only override the icon for the software title and fleet where they are added.
- `⁠version` specifies the app version. Available versions are listed in the Fleet UI under **Actions > Versions**. If omitted, Fleet automatically downloads the latest version found in [Fleet's catalog](https://fleetdm.com/software-catalog). The `version` must be wrapped in quotes (e.g. "147.0.1") so that it is processed as a string.
Expand Down
Loading