Workbrew Deployment Guide: Fleet

Before you begin following this guide, you should:

• Have access to a Fleet instance,  
  
  • with user privileges to:
    
    • Create an API token,
    • Add, edit, and delete software,
    • Install/uninstall software on hosts,
  • Check the Fleet prerequisites for custom packages.
• A Workbrew workspace:
  
  • New to Workbrew? Create a free account and follow the Getting Started guide.
• Be aware of the system requirements for Workbrew (and Homebrew):
  
  • Everything Homebrew requires:
    
    • An Apple Silicon CPU or 64-bit Intel CPU.
    • macOS Ventura (13) (or higher) installed on officially supported hardware.
    • The Bourne-again shell for installation (i.e. bash).
    • Don’t worry about the Command Line Tools (CLT) for Xcode requirement, Xcode CLT will be installed as part of deployment.
  • Device enrolled in Fleet.
  • User account in the `admin` group or in the `workbrew_users` group.

Are you an experienced Fleet administrator? These steps will get you up and going quickly. Read on for more detailed explanations.

1. In Fleet, retrieve your API token. It is recommended you create an API-only user for token management.
2. In the Workbrew console, enter the workspace settings and select Fleet as the MDM Type. Enter your Fleet API token, and then save the Workbrew Workspace API key and installation script.
3. In Fleet, add the Workbrew .pkg as a new custom package.  
   
   1. Select the hosts to deploy to using Target,
   2. Edit the install script to include the Workbrew Workspace API key and installation script,
   3. Optionally, enable self-service and automatic install.
4. In the Workbrew console, after deployment to a device, check Devices to ensure the expected device appears (please be aware that device inventory is updated periodically, not in real time).
5. If needed, check the Troubleshooting guide and FAQ or contact us for support.

Workbrew is installed using a signed .pkg file, which installs several components:

• The Workbrew agent,
• The Secure Workbrew CLI, a wrapper around the standard Homebrew CLI.

In addition to installing the Workbrew .pkg on each device, you must run a (bash) script which connects the Workbrew agent to your Workbrew Console. The script also installs Command Line Tools for Xcode if your devices do not already have it. The Workbrew Console connection wizard will guide you through customization to your install script.

You can deploy the Workbrew .pkg as a custom package, with the setup script appended to the default installation script. When creating the package, you can choose the hosts to deploy Workbrew through setting a target, and can optionally enable both self-service and automatic installation.

In brief, you will perform these steps to ready Workbrew for deployment:

• Create a Fleet API Token,
• Complete the Workbrew Console connection wizard, adding the API Token in the process,
• Add the Workbrew Package and setup script to Fleet,
• Select your deployment targets,
• Optionally, make the custom package available for self service.

Creating an API Token in Fleet

To populate your Workbrew Console with information about your devices and users, Workbrew requires Read-Only API access to your Fleet instance. In Fleet, API tokens belong to user accounts, and tokens for regular users expire. API-only user tokens do not expire, and allow for more secure management of tokens, so recommend always using an API-only user for token generation.

Follow the instructions in the Fleet Documentation to Create an API-only user. Save the resulting token for the next step.

Add Fleet to your Workbrew workspace

The API token created in the previous step will allow Workbrew to read from your Fleet instance using the API. In this section, you will register Fleet as your MDM of choice within Workbrew.

• From the Workbrew Console, select MDM.
• Under MDM Type, select “Fleet”.
• Under Fleet Host, enter your Fleet instance URL.
• In the Fleet API Token field, enter the API token generated in the previous section.
• Click Update Workspace.
• Open Workbrew Workspace API key and installation script, copy the script, and store it for later. This script will run as part of the installation script of the custom package.

Add the package

The Workbrew .pkg installs Workbrew, including the agent, CLI, and Homebrew. In this section, you will add the package to Fleet so that it can be distributed to your selected hosts. It can also optionally be made available via self service.

Download the package, and then follow the instructions under Add a custom package, stopping once you reach “To customize installer behavior, click on “Advanced options.”.

At this point, expand Advanced options. Edit the install script and append the Workbrew setup script you saved in the previous step, after the existing content. Both the contents of the install script box and the Workbrew setup script begin with `#!/bin/bash`: when pasting in the Workbrew setup script, remove the `#!/bin/bash` so that only one `#!/bin/bash` remains in the first line of the install script box.

Click Add software to complete the process and add Workbrew to Fleet.

Workbrew will be distributed to the hosts chosen in target when setting up the custom package. If you skipped that step or need to add assignments in the future, you can access the package through Software and edit it to add additional targets.  Once Workbrew has been deployed to a device, it will appear on the Workbrew Console.

• Getting Started
• Frequently Asked Questions
• Troubleshooting
• Workbrew Blog