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

Contributing Fleet-maintained apps (#35235)

Browse Source 
- Simplify steps. Why? Fewer handoffs / approvals
- #g-software EM reviews all PRs within 3 business days
- Commit to automated tests. No need to do manual testing because the CI
already installs the app and checks, via osquery, if the
install/uninstalls worked
- Remove issue template

Why now?
- https://github.com/fleetdm/confidential/issues/12844

---------

Co-authored-by: Martin Angers <martin.n.angers@gmail.com>
Co-authored-by: George Karr <georgekarrv@users.noreply.github.com>
This commit is contained in:
Noah Talerman
2025-11-14 10:12:24 -06:00
committed by GitHub
co-authored by Martin Angers George Karr
parent b7742c9c20
commit 1c1e19197c
3 changed files with 58 additions and 266 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/ISSUE_TEMPLATE/fma-request.md
-37
View File
@@ -1,37 +0,0 @@
---
name: 📦 New Fleet-maintained app
about: Request to add an app to the Fleet-maintained app catalog
title: 'New FMA: <App Name>'
labels: ':release,#g-software,fma'
assignees: 'marko-lisica'
---
### Requestor
- Application name: TODO
- Application platform: TODO (macOS/Windows)
---
### Validation
- [ ] The following outputs are generated
- `/outputs/<app-name>/darwin.json` created
- `/outputs/apps.json` updated
- [ ] Manifest name matches osquery `app.name` (macOS) or `programs.name` (Windows)
- [ ] Manifest version scheme matches osquery `app.short_bundle_version` (macOS) or `programs.version` (Windows) version scheme
- [ ] Manifest `unique_identifier` matches osquery `app.bundle_identifier` (macOS only)
### QA
- [ ] App adds successfully to team's library
- [ ] App installs successfully on host
- [ ] App opens successfully on host
- [ ] App uninstalls successfully on host
### Icon
- [ ] Icon added to Figma
- [ ] Icon added to Fleet
- [ ] Correct icon appears in the app catalog
ee/maintained-apps/README.md
+57 -228
View File
@@ -2,11 +2,10 @@
## Adding a new app (macOS)
1. Create a new issue using the [New Fleet-maintained app](https://github.com/fleetdm/fleet/issues/new?template=fma-request.md) issue template
2. Find the app's metadata in its [Homebrew formulae](https://formulae.brew.sh/)
3. Create a new mainfiest file called `$YOUR_APP_NAME.json` in the `inputs/homebrew/` directory. For
1. Find the app's metadata in its [Homebrew formulae](https://formulae.brew.sh/)
2. Create a new manifest file called `$YOUR_APP_NAME.json` in the `inputs/homebrew/` directory. For
example, if you wanted to add Box Drive, create the file `inputs/homebrew/box-drive.json`.
4. Fill out the file according to the [input schema below](#input-file-schema). For our example Box Drive app, it would look like this:
3. Fill out the file according to the [input schema below](#input-file-schema). For our example Box Drive app, it would look like this:
```json
{
@@ -19,168 +18,47 @@
}
```
5. Run the following command from the root of the Fleet repo to generate the app's output data:
4. Run the following command from the root of the Fleet repo to generate the app's output data:
```bash
go run cmd/maintained-apps/main.go --slug="<slug-name>" --debug
```
5. The contributor is responsible for adding the icon to Fleet (e.g. the TypeScript and website PNG components of [#29175](https://github.com/fleetdm/fleet/pull/29175/files)). These are generated using the [generate-icons](https://github.com/fleetdm/fleet/tree/main/tools/software/icons) script.
6. Add a description for the app in `outputs/apps.json` file. You can use descriptions from [Homebrew formulae](https://formulae.brew.sh/).
7. Open a PR to the `fleet` repository with the above changes. Connect it to the issue by adding `Fixes #ISSUE_NUMBER` in the description.
7. Open a PR to the `fleet` repository with the above changes. The [#g-software Engineering Manager (EM)](https://fleetdm.com/handbook/company/product-groups#software-group) is automatically added reviewer. Also, @ mention the #g-software Product Designer (PD) in a comment that points them to the new icon. This way, the icon change gets a second pair of eyes.
8. The [#g-software product group](https://fleetdm.com/handbook/company/product-groups#software-group) will:
1. Review the PR and test the app. Contributors should be aware of the validation requirements below.
2. If validation requirements cannot be met in this PR, the PR will be closed and the associated issue will be prioritized in the g-software group backlog.
8. If the app passes automated tests, it is approved and merged. The EM reviews the PR within 3 business days. The app should appear shortly in the Fleet-maintained apps section when adding new software to Fleet. The app icon will not appear in Fleet until the following release.
9. If the app passes testing, it is approved and merged. The app should appear shortly in the Fleet-maintained apps section when adding new software to Fleet. The app icon will not appear in Fleet until the following release. App icon progress is tracked in the issue. An addition to Fleet-maintained apps is not considered "Done" until the icon is added in a Fleet release. This behavior will be [improved](https://github.com/fleetdm/fleet/issues/29177) in a future release.
### macOS input file schema
### Input file schema
#### `name` (required)
This is the user-facing name of the application.
#### `unique_identifier` (required)
This is the platform-specific unique identifier for the app. On macOS, this is the app's bundle identifier.
#### `token` (required)
This is the identifier used by homebrew for the app; it is the `token` field on the homebrew API response.
#### `installer_format` (required)
This is the file format for the app's installer. Currently supported values are:
- `zip`
- `dmg`
- `pkg`
To find the app's installer format, you can look at the `url` field on the homebrew API response. The installer's extension should be at the end of this URL.
Sometimes the file type is not included in the installer's URL. In this case, you can download the installer and use the extension of the downloaded file.
#### `slug` (required)
The `slug` identifies a specific app and platform combination. It is used to name the manifest files that contain the metadata that Fleet needs to add, install, and uninstall this app. This is what is used when referring to the app in GitOps.
The slug is composed of a filesystem-friendly version of the app name, and an operating system platform identifier, separated by a `/`.
For the app name part, use `-` to separate words if necessary, for example `adobe-acrobat-reader`.
Use `darwin` as the platform part. For example, use a `slug` of `box-drive/darwin` for Box Drive on macOS.
#### `pre_uninstall_scripts` (optional)
These are command lines that will be run _before_ the generated uninstall script is executed, e.g. for [Box](inputs/homebrew/box-drive.json).
#### `post_uninstall_scripts` (optional)
These are command lines that will be run _after_ the generated uninstall script is executed, e.g. for [Box](inputs/homebrew/box-drive.json).
#### `default_categories` (required)
These are the default categories assigned to the installer in [self-service](https://fleetdm.com/guides/software-self-service) if no categories are specified when it is added to a team's library. Categories must be one or more of these values:
- `Browsers`
- `Communication`
- `Developer Tools`
- `Productivity`
#### `install_script_path` (optional)
This is a filepath to an install script. If provided, this script will be used instead of the generated install script. Only shell scripts (`.sh`) are supported.
The script should be added to the `inputs/homebrew/scripts` directory.
#### `uninstall_script_path` (optional)
This is a filepath to an uninstall script. If provided, this script will be used instead of the generated uninstall script. Only shell scripts (`.sh`) are supported.
`uninstall_script_path` can't be used together with `pre_uninstall_scripts` and `post_uninstall_scripts`.
The script should be added to the `inputs/homebrew/scripts` directory.
| Name | Type | Description |
|--------------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `name` | string | **Required.** User-facing name of the application. |
| `unique_identifier` | string | **Required.** Platform-specific unique identifier (e.g., bundle identifier on macOS). |
| `token` | string | **Required.** Homebrew's unique identifier. It's the `token` field of the Homebrew API response. |
| `installer_format` | string | **Required.** File format of the installer (`zip`, `dmg`, `pkg`). Determine via the file extension in the Homebrew API `url` field or by downloading the installer if the extension isn’t present. |
| `slug` | string | **Required.** Identifies the app/platform combination (e.g., `box-drive/darwin`). Used to name manifest files and reference the app in [Fleet's best practice GitOps](https://fleetdm.com/docs/configuration/yaml-files#fleet-maintained-apps). Format: `<app-name>/<platform>`, where app name is filesystem-friendly and platform is `darwin`. |
| `default_categories` | string | **Required.** Default categories for self-service if none are specified. Valid values: `Browsers`, `Communication`, `Developer Tools`, `Productivity`. |
| `pre_uninstall_scripts` | string | Command lines run **before** the generated uninstall script (e.g., for [Box](inputs/homebrew/box-drive.json)). |
| `post_uninstall_scripts` | string | Command lines run **after** the generated uninstall script (e.g., for [Box](inputs/homebrew/box-drive.json)). |
| `install_script_path` | string | Filepath to a custom install script (`.sh`). Overrides the generated install script. Script must be placed in `inputs/homebrew/scripts/`. |
| `uninstall_script_path` | string | Filepath to a custom uninstall script (`.sh`). Overrides the generated uninstall script. Cannot be used together with `pre_uninstall_scripts` or `post_uninstall_scripts`. Script must be placed in `inputs/homebrew/scripts/`. |
## Adding a new app (Windows)
Use the Winget ingester. You will author:
- An input JSON in `ee/maintained-apps/inputs/winget/`
- Optional PowerShell scripts in `ee/maintained-apps/inputs/winget/scripts/`
1. Find the Winget PackageIdentifier in the [winget-pkgs repo](https://github.com/microsoft/winget-pkgs).
### Can I do this on macOS?
2. Get the unique identifier that Fleet will use for matching the software with software inventory:
- On a test Windows host, install the app manually, then run the following PowerShell script: `Get-ItemProperty 'HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*' | Where-Object {$_.DisplayName -like '*<App Name>*'} | Select-Object DisplayName, DisplayVersion, Publisher`
- Use the exact value from `DisplayName` as the `unique_identifier`.
The instructions below are meant to be run on a Windows host. But, you can run most of this on a macOS host, as well:
- You can author Windows inputs and run the generator on macOS. The ingester is Go code that fetches data from winget/GitHub and works cross‑platform.
- To find a Winget PackageIdentifier without a Windows host, browse the winget-pkgs repo: https://github.com/microsoft/winget-pkgs (search for your app’s manifests).
- To find the PackageName and Publisher, you can look in the locale and installer yaml files in the winget-pkgs repo.
- Validation and testing still require a Windows host (to verify programs.name and to run install/uninstall).
If the `unique_identifier` doesn't match the `DisplayName`, then Fleet will incorrectly create two software titles when the Fleet-maintained app is added and later installed. One title for the Fleet-maintained app and a separate title for the inventoried software.
### Step 1: Find the Winget PackageIdentifier
- On a Windows host, run: `winget search <app name>`
- Note the `PackageIdentifier`. For example, Box Drive is typically `Box.Box`.
3. Fill out the file according to the [input schema](#windows-input-file-schema). For example, Box Drive looks like this:
### Step 2: Find the unique identifier used by osquery
The Windows ingester expects `unique_identifier` to match the value in `programs.name` on the host after install (this is what Fleet uses to confirm the app exists).
- On a test Windows host, install the app manually, then check either:
- Fleet live query: `SELECT name, version, publisher FROM programs WHERE name LIKE '%<App Name>%';`
- PowerShell: `Get-ItemProperty 'HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*' | Where-Object {$_.DisplayName -like '*<App Name>*'} | Select-Object DisplayName, DisplayVersion, Publisher`
- Use the exact `DisplayName`/`programs.name` string as `unique_identifier`.
### Step 3: Choose installer metadata
If the winget manifest supports multiple installers, these fields select the right one:
- `installer_arch`: `x64` or `x86` (most apps use `x64`)
- `installer_type`: `exe`, `msi`, or `msix` (file type, not vendor tech like "wix")
- `installer_scope`: `machine` or `user` (prefer `machine` for managed installs)
- Optional: `installer_locale` if a specific locale is required
- Optional: `program_publisher`, `uninstall_type`, `fuzzy_match_name` (rare)
- `default_categories`: one or more of: `Browsers`, `Communication`, `Developer Tools`, `Productivity`
Tip: Setting these accurately avoids ambiguity when multiple installers exist.
### Step 4: Provide install/uninstall scripts
How scripts work:
- MSI installers: The ingester automatically generates install and uninstall scripts. Do not add scripts unless you need to override the generated behavior.
- EXE installers: You must provide PowerShell scripts that run the installer file directly. Fleet stores the installer and sends it to the host at install time; your script must execute it using the INSTALLER_PATH environment variable.
Place scripts in `ee/maintained-apps/inputs/winget/scripts/`.
Example install script `ee/maintained-apps/inputs/winget/scripts/box_drive_install.ps1`:
```powershell
# Install system-wide, silent
# Learn more about .exe install scripts:
# http://fleetdm.com/learn-more-about/exe-install-scripts
$exeFilePath = "${env:INSTALLER_PATH}"
try {
# Silent arguments vary by installer (e.g., /S, /silent, /VERYSILENT)
$processOptions = @{
FilePath = "$exeFilePath"
ArgumentList = "/VERYSILENT /NORESTART"
PassThru = $true
Wait = $true
}
$process = Start-Process @processOptions
$exitCode = $process.ExitCode
Write-Host "Install exit code: $exitCode"
Exit $exitCode
}
catch {
Write-Host "Error: $_"
Exit 1
}
```
Uninstall scripts for EXE installers are vendor-specific. Use the vendor’s documented silent uninstall switch or the registered UninstallString (if available), ensuring the script runs silently and returns the installer’s exit code.
For MSI installers, you can omit scripts; for EXE installers, scripts are required.
### Step 5: Create the Winget input JSON
Create `ee/maintained-apps/inputs/winget/box-drive.json`:
```json
{
"name": "Box Drive",
@@ -193,99 +71,50 @@ Create `ee/maintained-apps/inputs/winget/box-drive.json`:
"default_categories": ["Productivity"]
}
```
Notes:
- `slug` uses `<app-name>/windows` (lowercase, dash-separated name)
- `unique_identifier` must match `programs.name` exactly
### Step 6: Generate outputs
From the repo root:
4. Run the following command from the root of the Fleet repo to generate the app's output data:
```bash
go run cmd/maintained-apps/main.go --slug="box-drive/windows" --debug
```
This updates/creates:
- `ee/maintained-apps/outputs/apps.json` (catalog entry)
- `ee/maintained-apps/outputs/box-drive/windows.json` (manifest + script refs)
### Step 7: Add description
Edit `ee/maintained-apps/outputs/apps.json` to add a human-friendly `description` for your app’s entry. For Windows entries, use the vendor description (from the winget manifest or vendor site).
5. The contributor is responsible for adding the icon to Fleet (e.g. the TypeScript and website PNG components of [#29175](https://github.com/fleetdm/fleet/pull/29175/files)). These are generated using the [generate-icons](https://github.com/fleetdm/fleet/tree/main/tools/software/icons) script.
### Step 8: Test in a Fleet instance
- Set an override to point your Fleet instance at your branch’s catalog:
```bash
export FLEET_DEV_MAINTAINED_APPS_BASE_URL="https://raw.githubusercontent.com/<repository-name>/fleet/refs/heads/<PR-branch-name>/ee/maintained-apps/outputs"
```
- Trigger a refresh:
```bash
fleetctl trigger --name maintained_apps
```
- Add the app to a team, deploy to a Windows host, and verify:
- Install completes
- App launches
- App uninstalls cleanly
6. Add a description for the app in outputs/apps.json file. You can use descriptions from the wingest manifest.
### Step 9: Open the PR
- Include “Fixes #<issue-number>” and any validation notes/screenshots
- The software group will review, validate, and merge when ready
7. Open a PR to the fleet repository with the above changes. The [#g-software Engineering Manager (EM)](https://fleetdm.com/handbook/company/product-groups#software-group) is automatically added reviewer. Also, @ mention the #g-software Product Designer (PD) in a comment that points them to the new icon. This way, the icon change gets a second pair of eyes.
8. If the app passes automated tests, it is approved and merged. The EM reviews the PR within 3 business days. The app should appear shortly in the Fleet-maintained apps section when adding new software to Fleet. The app icon will not appear in Fleet until the following release.
### Windows input file schema
| Name | Type | Description |
|--------------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `name` | string | **Required.** User-facing name of the application. |
| `unique_identifier` | string | **Required.** Platform-specific unique identifier. For Windows, this is the `DisplayName`. |
| `package_identifier` | string | **Required.** The `PackageIdentifier` from winget. Fleet uses this to pull the correct metadata for the app. |
| `slug` | string | **Required.** Identifies the app/platform combination (e.g., `box-drive/windows`). Used to name manifest files and reference the app in [Fleet's best practice GitOps](https://fleetdm.com/docs/configuration/yaml-files#fleet-maintained-apps). Format: `<app-name>/<platform>`, where app name is filesystem-friendly and platform is `darwin`. |
| `installer_arch` | string | **Required.** `x64` or `x86` (most apps use `x64`). |
| `installer_type` | string | **Required.** `exe`, `msi`, or `msix` (file type, not vendor tech like "wix") |
| `installer_scope` | string | **Required.** `machine` or `user` (prefer `machine` for managed installs) |
| `default_categories` | string | **Required.** Default categories for self-service if none are specified. Valid values: `Browsers`, `Communication`, `Developer Tools`, `Productivity`. |
| `install_script_path` | string | Filepath to a custom install script (`.ps1`). Overrides the generated install script. Script must be placed in `inputs/winget/scripts/`. For `.msi` apps, the ingestor automatically generates install scripts. Do not add scripts unless you need to override the generated behavior. For `.exe` apps, you must provide PowerShell scripts that run the installer file directly. Fleet stores the installer and sends it to the host at install time; your script must execute it using the `INSTALLER_PATH` environment variable. |
| `uninstall_script_path` | string | Filepath to a custom uninstall script (`.ps1`). Overrides the generated uninstall script. Script must be placed in `inputs/winget/scripts/`. For `.msi` apps, the ingestor automatically generates uninstall scripts. Do not add scripts unless you need to override the generated behavior. For `.exe` apps, you must provide a script to uninstall the app. Scripts for `.exe` apps are vendor-specific. Use the vendor’s documented silent uninstall switch or the registered UninstallString (if available), ensuring the script runs silently and returns the installer’s exit code. |
| `fuzzy_match_name` | boolean | If the `unique_identifier` doesn't match the `DisplayName`, use `fuzzy_match_name` to specify that Fleet uses "fuzzy matching" to match the Fleet-maintained app and the inventoried software. For example, for Pritunl, the `unique_identifier` is "Pritunl" and the inventories software's `DisplayName` is "Pritunl Client". With `fuzzy_match_name` set to true, Pritunl app will be matched to the inventories software. |
#### Windows troubleshooting
### Troubleshooting (Windows)
- App not found in Fleet UI: ensure `apps.json` was updated by the generator and your override URL is correct
- Install fails silently: confirm your `installer_type`, `installer_arch`, and `installer_scope` match the selected winget installer; run your PowerShell script manually on a test host
- Uninstall doesn’t remove the app: prefer explicit uninstall scripts; otherwise, ensure the winget manifest exposes `ProductCode` or `UpgradeCode`
- Hash mismatch errors: if the upstream manifest is in flux, you can set `ignore_hash: true` in the input JSON (use sparingly)
#### Can I do this on macOS?
### Validating Fleet-maintained apps additions
1. When a pull request (PR) is opened containing changes to `ee/maintained-apps/inputs/`, the [#g-software Product Designer (PD) and Engineering Manager (EM)](https://fleetdm.com/handbook/company/product-groups#software-group) are automatically added as reviewers.
1. The PD is responsible for approving the name and default category
2. The EM is repsonsible for validating or assigning a validator
2. Ensure an associated issue exists for the PR. If not, create one using the `Add Fleet-maintained app` issue template. Move the issue to the `g-software` project and set the status to `In Progress`. Ensure the PR is linked to the issue.
3. Validate the PR:
1. Find the app in [Homebrew's GitHub casks](https://github.com/Homebrew/homebrew-cask/tree/main/Casks) and download it locally using `cask.url`.
2. Install it on a host and run a live query on the host: `SELECT * FROM apps WHERE name LIKE '%App Name%';`
3. Validate and check off items in the `Validation` section of the issue.
4. If the PR passes validation, the validator will also execute the test criteria in the QA section of the issue. If tests fail, add feedback in the PR comments. If the test failure(s) cannot be addressed by the contributor, close the PR and move the issue to the Drafting board for prioritization. If tests pass, the PR is approved and merged.
5. The validator is responsible for adding the icon to Fleet (e.g. the TypeScript and website PNG components of [#29175](https://github.com/fleetdm/fleet/pull/29175/files)). These can be generated using the [generate-icons](https://github.com/fleetdm/fleet/tree/main/tools/software/icons) script.
6. QA ensures the icon is added to Fleet
#### Testing additions to Fleet-maintained apps (no icon)
Use the `FLEET_DEV_MAINTAINED_APPS_BASE_URL` environment variable with the following value:
```bash
https://raw.githubusercontent.com/<repository-name>/fleet/refs/heads/<PR-branch-name>/ee/maintained-apps/outputs
```
Make sure you replace the `<PR-branch-name>` and `<repository-name>`
By default, Fleet refreshes the maintained apps catalog on a schedule.
To fetch your branch’s catalog immediately (without waiting), run:
```bash
fleetctl trigger --name maintained_apps
```
Test criteria:
- [X] App adds successfully to team's library
- [X] App installs successfully on host
- [X] App opens succuessfully on host
- [X] App uninstalls successfully on host
If the tests pass:
- Move issue to `Ready` (icon addition still needed)
- Approve and merge PR
If testing fails:
- Remove issue from the `g-software` release board, and add issue to the `Drafting` board. Remove the `:release` tag and add the `:product` tag.
The instructions below are meant to be run on a Windows host. But, you can run most of this on a macOS host, as well:
- You can author Windows inputs and run the generator on macOS. The ingester is Go code that fetches data from winget/GitHub and works cross‑platform.
- To find the PackageName and Publisher, you can look in the locale and installer yaml files in the winget-pkgs repo.
- Validation and testing still require a Windows host (to verify programs.name and to run install/uninstall).
## Updating existing Fleet-maintained apps
website/config/custom.js
Vendored
+1 -1
View File
@@ -190,7 +190,7 @@ module.exports.custom = {
'.github/ISSUE_TEMPLATE': 'sampfluger88',
// 💝 Fleet-maintained apps
'ee/maintained-apps/inputs': 'mostlikelee',
'ee/maintained-apps/inputs': 'georgekarrv',
},
// FUTURE: Support DRIs for confidential and other repos (except see other note above about a consolidated way to do it, to reduce these 4-6 config keys into one)