Discharge7443/fleet
1
0
Fork 0
Code Issues Pull Requests Actions 16 Packages Projects Releases Wiki Activity

Add Fleet-maintained apps process docs: handbook section and customer-facing article (#49520)

Browse Source 
**Related issue:** N/A (documentation, handbook, and article changes
only)

## Details

Gives Fleet-maintained apps (FMAs) customer-facing documentation of the
process behind the catalog:

- **New handbook section** (`handbook/company/product-groups.md` >
"Fleet-maintained apps"): what FMAs are, how the catalog is kept up to
date (4-hour upstream checks, automated PRs, validation on real hosts,
human review, hourly server refresh), the freeze process, security
expectations (vendor-direct downloads, pinned SHA-256 hashes,
open-source manifests and scripts), service level objectives, and how to
request or contribute an app.
- **New article** (`articles/inside-fleet-maintained-apps.md`, publishes
to `fleetdm.com/articles/inside-fleet-maintained-apps`): a
customer-facing explainer of the same pipeline with a mermaid diagram of
the add/review/validation workflow, coverage of automatic updates,
version pinning, and patch policies, the security model, and a
contributor section highlighting the repo's `new-fma` Claude Code skill.
Follows Fleet's article format (dek, key takeaways, CTA button).
- **Cross-links** from the existing FMA guide
(`articles/fleet-maintained-apps.md`) and between the handbook section
and the article.

## Notes for reviewers

- The SLO "Publish a validated app update within 1 business day of
detection" in the handbook table is a **new public commitment**. The
other numbers (4-hour ingest checks, hourly server catalog refresh,
3-business-day review of new app PRs) are grounded in the existing
workflows, server cron intervals, and the FMA contributor README. Please
confirm the 1-business-day target before merging.
- The article's author meta is Allen Houchins with a publish date of
2026-07-17; adjust if it should ship later or under a different author.
- All process claims were verified against the repo:
`.github/workflows/ingest-maintained-apps.yml`, `cmd/fleet/cron.go`
(hourly `maintained_apps` schedule),
`ee/server/service/maintained_apps.go` (SHA-256 verification and
`no_check` behavior), and `ee/maintained-apps/README.md` (contribution
and freeze process).

# Checklist for submitter

- [x] Documentation, handbook, and article changes only. No product code
changes, so the changes-file, testing, database migration,
configuration, and fleetd checklists don't apply.
- [x] Manually verified all links resolve (website routes, GitHub paths,
in-page anchors) and that the website renders mermaid code blocks
(`website/views/layouts/layout.ejs` loads `mermaid.min.js`; precedent in
`articles/enroll-hosts.md`).
This commit is contained in:
Allen Houchins
2026-07-21 12:51:25 -05:00
committed by GitHub
parent d81902f83b
commit 133a05e93b
2 changed files with 104 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
articles/fleet-maintained-apps.md
+2
View File
@@ -123,6 +123,8 @@ Fleet:
- fetches an individual app's manifest when the **Add** button is pressed from the maintained apps list in the UI, and when an individual app is [retrieved](https://fleetdm.com/docs/rest-api/rest-api#get-fleet-maintained-app) or [added](https://fleetdm.com/docs/rest-api/rest-api#add-fleet-maintained-app) via the REST API
- DOES NOT directly pull data from WinGet or Homebrew to end-user devices
For a deeper look at the whole pipeline, including validation on real hosts, how broken updates are frozen, and the security model, see [how Fleet keeps Fleet-maintained apps safe and up to date](https://fleetdm.com/articles/inside-fleet-maintained-apps).
<meta name="category" value="guides">
<meta name="authorFullName" value="Gabriel Hernandez">
<meta name="authorGitHubUsername" value="ghernandez345">
articles/inside-fleet-maintained-apps.md
+102
View File
@@ -0,0 +1,102 @@
# How Fleet keeps Fleet-maintained apps safe and up to date
*Every app in Fleet's catalog is downloaded straight from the vendor, verified against a pinned hash, tested on real hardware, and reviewed by a human before your hosts ever see it. Here's the pipeline behind the catalog.*
## Key takeaways
- **Installers come straight from the vendor.** Fleet never re-hosts or modifies an installer. Your Fleet server downloads each app from the vendor's official distribution URL and verifies its SHA-256 hash before storing it.
- **The catalog updates itself.** Fleet checks upstream package sources every 4 hours, so a new release from an app vendor becomes an update candidate the same day it ships.
- **Nothing is published untested.** Every catalog change installs and uninstalls on real macOS and Windows hosts before a Fleet team member reviews and merges it.
- **Broken updates get frozen, not shipped.** If a new version fails validation, Fleet holds the app at the last version that worked and files a bug, so a bad update never replaces a good one.
- **Your hosts stay current without babysitting.** Apps update to the latest validated version by default, you can pin versions for change control, and patch policies remediate hosts running outdated software automatically.
- **Everything is auditable.** App manifests and install and uninstall scripts are open source, so you can read exactly what runs on your hosts and see the history of every change.
<a purpose="cta-button" href="/software-catalog">Browse the app catalog</a>
When you let a device management vendor install software on every computer in your company, you're trusting their supply chain as much as your own. Most vendors ask you to take that on faith.
We'd rather show you the pipeline. [Fleet-maintained apps](https://fleetdm.com/guides/fleet-maintained-apps) are a catalog of popular macOS and Windows applications that Fleet keeps installable, uninstallable, and up to date for you. Every app in the catalog moves through the same automated, publicly visible workflow before it reaches your hosts. Here's how it works.
## Where the catalog comes from
Fleet doesn't invent its own record of where each app lives. Metadata comes from the same upstream sources trusted by millions of developers: [Homebrew casks](https://formulae.brew.sh/) for macOS and [winget manifests](https://github.com/microsoft/winget-pkgs) for Windows. Automation [checks these sources every 4 hours](https://github.com/fleetdm/fleet/blob/main/.github/workflows/ingest-maintained-apps.yml). When a vendor ships a new version, that automation opens a pull request in the public [fleetdm/fleet repository](https://github.com/fleetdm/fleet/tree/main/ee/maintained-apps) that updates the app's version, download URL, and SHA-256 hash, and regenerates its install and uninstall scripts.
New apps enter the catalog the same way. A Fleet team member or community contributor writes an input manifest and opens a pull request. If you'd like to add an app yourself, see [contribute an app to the catalog](#contribute-an-app-to-the-catalog) below, or [file a request](https://fleetdm.com/feature-request) and let us do the work.
## Validation on real hosts
Before any change merges, automated tests download each changed app and put it through the full lifecycle on real hardware: install it, confirm the app actually exists on the host afterward, then uninstall it and confirm it's gone. macOS apps validate on macOS hosts, and Windows apps validate on x64 or Arm hardware to match the installer's architecture.
A change that passes still doesn't merge on its own. A Fleet team member reviews every pull request before it's published. A change that fails doesn't ship at all: Fleet freezes the app at the last version that installed successfully and files a bug. Freezing has one honest trade-off. If the vendor removes the download link for the older version while the app is frozen, installs of that app fail until Fleet publishes a fixed version. We think that beats the alternative of silently shipping an update we couldn't verify.
## The lifecycle at a glance
```mermaid
graph TD;
vendor["App vendor releases a new version"] --> upstream["Homebrew cask or winget manifest updates"];
upstream --> ingest["Fleet checks upstream sources every 4 hours"];
ingest --> pr["Pull request with updated version, download URL,<br>SHA-256 hash, and regenerated scripts"];
contributor["New app from a Fleet team member<br>or community contributor"] --> pr;
pr --> ci["Automated validation on real macOS and Windows hosts:<br>download, install, verify, uninstall"];
ci -- Pass --> review["Fleet team member reviews and merges"];
ci -- Fail --> freeze["App frozen at last working version, bug filed"];
review --> publish["Published to the Fleet-maintained apps catalog"];
publish --> server["Your Fleet server refreshes the catalog hourly"];
server --> hosts["Hosts install and update apps via self-service,<br>manual install, or policy automation"];
```
## How apps on your hosts stay updated
Once a change is published, your Fleet server picks it up on its own. The server refreshes the catalog every hour, or immediately when you run `fleetctl trigger --name=maintained_apps`. You don't need to upgrade Fleet to get new apps or new versions.
By default, Fleet-maintained apps track the latest validated version. When a vendor releases an update, Fleet uses it for new installs, and hosts running an older version move to the latest one the next time the app is installed, whether through [self-service](https://fleetdm.com/guides/software-self-service), a manual install, or a [policy automation](https://fleetdm.com/guides/automatic-software-install-in-fleet). If your change control process needs more predictability, [pin an app to a specific or major version](https://fleetdm.com/guides/fleet-maintained-apps#pin-a-version), and if an update introduces a bug, roll back by pinning the previous version.
Patch policies close the loop on hosts that fall behind. Add one from the app's details page under **Actions > Patch**, and Fleet generates a policy that detects hosts running outdated versions. Enable the install automation at **Policies > Manage automations > Install software**, and hosts that fail the policy get the update installed automatically. With [GitOps](https://fleetdm.com/docs/configuration/yaml-files#patch-policy), the patch policy's query updates itself to reference the latest version each time your specs are applied, so the policy never goes stale. The result is a chain with no manual links: the vendor releases, Fleet validates and publishes, your server syncs, and your hosts remediate.
## The security model
The catalog's security rests on a few plain commitments:
- **Vendor-direct downloads.** Fleet never re-hosts or modifies installers. When you add or update an app, your Fleet server downloads the installer from the vendor's official distribution URL, the same place you'd get it yourself.
- **Pinned hashes.** Each app version records the SHA-256 hash published in the upstream package manifest, and your Fleet server rejects a downloaded installer that doesn't match. Some vendors only publish rolling "latest" URLs that can't be pinned in advance. For those apps, Fleet records the installer's hash at download time instead.
- **Open source, end to end.** Every manifest, install script, and uninstall script lives in the public Fleet repository, and every change arrives as a pull request with its validation results attached. You never have to wonder what a Fleet-maintained app will run on your hosts. You can read it.
If you find a suspected security issue in a Fleet-maintained app, report it through Fleet's [vulnerability disclosure program](https://github.com/fleetdm/fleet/blob/main/SECURITY.md).
## Our service level objectives
These are the targets Fleet holds itself to for the catalog:
| Activity | Target |
|:---------|:-------|
| Check upstream package sources for new app versions | Every 4 hours |
| Publish a validated app update after a new version is detected | Within 1 business day |
| Customer Fleet servers pick up published catalog changes | Within 1 hour |
| Review community pull requests that add a new app | Within 3 business days |
## Contribute an app to the catalog
Anyone can propose a new Fleet-maintained app. The step-by-step instructions live in the [contributor README](https://github.com/fleetdm/fleet/blob/main/ee/maintained-apps/README.md): write a short input manifest describing the app, run the generator to produce its output manifest and its install and uninstall scripts, add the app's icon, and open a pull request. New app submissions get the same automated validation as everything else in the catalog, and a Fleet engineering manager reviews them within 3 business days.
If you use [Claude Code](https://claude.com/product/claude-code), the repository ships a skill that automates most of the work. Open Claude Code in your fleetdm/fleet checkout and ask it to "add X as a macOS FMA" or "add X as a Windows FMA". The [`new-fma` skill](https://github.com/fleetdm/fleet/blob/main/.claude/skills/new-fma/SKILL.md) follows the README's workflow and adds the hard-won gotchas it doesn't cover: it verifies the installed app's real identity with tools like msitools and PlistBuddy instead of trusting upstream metadata, and it handles bootstrapper installers and version-matching quirks that commonly trip up first-time contributors. You still review the result and open the pull request yourself, and automated validation and human review still apply.
## Trust, but verify us
Software supply chain attacks work because most update pipelines are invisible. You can't audit what you can't see. Fleet's answer is to make the entire path from vendor release to host install public: the sources, the scripts, the tests, and the review. Don't take our word for any of this. The repository is open, and so is the pull request history.
## See it live
- Follow the [Fleet-maintained apps guide](https://fleetdm.com/guides/fleet-maintained-apps) to add your first app.
- Set up [patch policies](https://fleetdm.com/guides/how-to-use-policies-for-patch-management-in-fleet) to remediate outdated hosts automatically.
- **Get a demo** of Fleet: [schedule a call](https://fleetdm.com/contact).
---
*Questions about how an app is maintained? [Open an issue](https://github.com/fleetdm/fleet/issues/new/choose) or ask in [#fleet on Slack](https://fleetdm.com/support).*
<meta name="articleTitle" value="How Fleet keeps Fleet-maintained apps safe and up to date">
<meta name="authorFullName" value="Allen Houchins">
<meta name="authorGitHubUsername" value="allenhouchins">
<meta name="category" value="articles">
<meta name="publishedOn" value="2026-07-17">
<meta name="description" value="Inside the Fleet-maintained apps pipeline: vendor-direct downloads, pinned hashes, validation on real hardware, human review, and automatic patching.">