fleet/ee/maintained-apps

Fleet-maintained apps (FMA)

Adding a new app (macOS)

1. Create a new issue using the New Fleet-maintained app issue template

2. Find the app's metadata in its Homebrew formulae

3. Create a new mainfiest 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. For our example Box Drive app, it would look like this:

   {
      "name": "Box Drive",
      "slug": "box-drive/darwin",
      "unique_identifier": "com.box.desktop",
      "token": "box-drive",
      "installer_format": "pkg",
      "default_categories": ["Productivity"]
   }
   

5. Run the following command from the root of the Fleet repo to generate the app's output data:

   go run cmd/maintained-apps/main.go --slug="<slug-name>" --debug
   

6. Add a description for the app in outputs/apps.json file. You can use descriptions from Homebrew formulae.

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.

8. The #g-software product 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.

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 in a future release.

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.

post_uninstall_scripts (optional)

These are command lines that will be run after the generated uninstall script is executed, e.g. for Box.

default_categories (required)

These are the default categories assigned to the installer in 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.

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) 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 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). These can be generated using the generate-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:

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:

fleetctl trigger --name maintained_apps

Test criteria:

• App adds successfully to team's library
• App installs successfully on host
• App opens succuessfully on host
• 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.

Updating existing Fleet-maintained apps

Fleet-maintained apps need to be updated as frequently as possible while maintaining reliability. This is currently a balancing act as both scenarios below result in customer workflow blocking bugs:

• App vendor updates to installers can break install/uninstall scripts
• App vendors will deprecate download links for older installers

A Github action periodically creates a PR that updates one or more apps in the catalog by:

• Bumping versions
• Regenerating install/uninstall scripts

Each app updated in the PR must be validated independently. Only merge the PR if all apps changed meet the following criteria:

• App can be downloaded using manifest URL
• App installs successfully on host using manifest install script
• App exists on host
• App uninstalls successfully on host using manifest uninstall script

If an app does not pass test criteria:

• Freeze the app
• File a bug for tracking

Freezing an existing Fleet-maintained app

If any app fails validation:

1. Do not merge the PR as-is.

2. Add "frozen": true" to the failing app's input file (e.g.,inputs/homebrew/<app>.json).

3. Revert its corresponding output manifest file (e.g., outputs/<slug>.json) to the version in the main branch:

   git checkout origin/main -- ee/maintained-apps/outputs/<slug>.json
   

4. Validate changes in the frozen input file by running the following. This should output no errors and generate no changes.

   go run cmd/maintained-apps/main.go --slug="<slug>" --debug
   

5. Commit both the input change and the output file revert to the same PR.