Set a Secret Brew Configuration
Petros Amoiridis
Enterprise
A Secret Brew Configuration sets a Homebrew environment variable whose value is masked in the Workbrew Console and never written to disk on your Devices. Use one when the value is a credential, such as a token for fetching private artifacts during an install. For non-sensitive variables, use a regular Brew Configuration instead.
To understand where a secret value is and is not available once you set it, see How Secret Brew Configurations stay secret.
Create a Secret Brew Configuration
- Go to Brew Configurations in the sidebar
- Click New Brew Configuration
- Set the Homebrew environment variable key to the variable name (for example
HOMEBREW_GITHUB_API_TOKEN) - Set the Homebrew environment variable value to the secret value
- Check Secret
- Choose the Device Group to target (or All Devices)
- Click Create Brew Configuration
The value is masked as bullets in the Brew Configurations list once saved.
Provision a token for private artifacts
The most common use is handing brew a token it needs while the Workbrew Agent runs an install or upgrade, for example a HOMEBREW_GITHUB_API_TOKEN for a formula that downloads a binary from a private GitHub repository, or a HOMEBREW_DOCKER_REGISTRY_TOKEN for a private registry.
Create the Secret Brew Configuration with the token as its value, target the Devices that need it, and the Agent injects it into the environment when it runs brew install, brew upgrade, or brew reinstall, and when it runs your Brew Commands and Default Packages. For the private tap case, pair this with the formula-side setup in How Workbrew authenticates private Taps.
Rotate or update a secret
To change a secret value, open the configuration from the Brew Configurations list and edit the Homebrew environment variable value field. The current value is shown in the edit form so you can confirm or replace it. Save to push the new value to the targeted Devices on their next check-in.
Scope and precedence
Like any Brew Configuration, a Secret Brew Configuration can apply workspace-wide or to a single Device Group, and a Device in more than one group resolves the value the same way every Brew Configuration does. See How policies apply to devices in multiple groups for the resolution rules.
Related docs
- How Secret Brew Configurations stay secret — where a secret value is and is not available once you set it, and why.
- How Workbrew authenticates private Taps — the most common reason to provision a token this way.
- How policies apply to devices in multiple groups — how workspace-wide and Device Group scopes resolve.
- Glossary — definitions of Brew Configurations, Brew Commands, and Default Packages.