How Workbrew authenticates private Taps

When you connect a GitHub or GitLab integration to your Workspace, Devices in your fleet can clone and update private Taps without any per-user credential configuration. This page explains how the authentication flow works and how it interacts with existing git credential setups.

The credential flow#

Workbrew installs a custom git credential helper (git-credential-workbrew) on each managed Device. When Homebrew runs a git operation that requires authentication, git invokes this helper instead of prompting the user or falling back to other credential managers.

The flow looks like this:

1. The Workbrew Agent runs brew update or installs a formula from a private Tap
2. Git needs credentials to access the private repository
3. Git calls git-credential-workbrew, which contacts the Workbrew Agent daemon running on the Device
4. The daemon requests a short-lived access token from the Workbrew Console API
5. The Console generates a token using the GitHub App installation or GitLab OAuth integration configured for the Workspace
6. The token is returned to git, which uses it to authenticate the request

Tokens are short-lived and cached briefly on the device. No long-lived secrets, SSH keys, or personal access tokens are stored on end-user machines.

GitHub vs. GitLab integrations#

For GitHub, Workbrew uses a GitHub App installation. When a Workspace admin installs the Workbrew GitHub App on their organization, the Console can generate installation access tokens scoped to the repositories the app has been granted access to.

For GitLab, Workbrew uses OAuth. The Console stores OAuth tokens for the integration and refreshes them automatically when they expire. This works with both GitLab.com and self-hosted GitLab instances.

In both cases, the credential helper on the Device handles authentication transparently. End users do not need to know which integration is in use.

Interaction with existing credential managers#

The Workbrew Agent runs Homebrew as a dedicated workbrew user. This user's git configuration is set up during installation to reset any inherited credential helpers and only use git-credential-workbrew. This means system-level credential helpers (like git-credential-manager or osxkeychain) are not invoked for Homebrew operations managed by Workbrew.

If a Device has git-credential-manager or another credential helper configured at the system level, it should not interfere with Workbrew's Homebrew operations. However, if you notice credential helper processes launching unexpectedly during brew update, check where the helper is configured by running:

git config --list --show-origin | grep credential

This will show whether the helper is set in a system-level config, a user-level config, or a repository-level config, which helps narrow down the source of the conflict.

What this does not cover#

Workbrew authenticates git operations for Taps (repository clones and fetches). It does not fetch or mirror external files referenced in a formula's url field. If a formula points to an artifact in a private location, that URL must be accessible to end users through other means, such as a public URL, a pre-signed URL, or credentials already configured on the user's device.

See Sync and authenticate private Taps with Workbrew for setup instructions.