Workbrew

https://workbrew.com/docs
Admin
Workbrew is a comprehensive platform providing advanced management and security features for...
Tokens:25,537
Snippets:418
Trust Score:8.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Verify Profile Installation

Source: https://workbrew.com/docs/preserve-app-settings-during-cask-upgrades

Use this command on a managed Mac to list installed profiles and confirm the presence of the Workbrew App Management Permission payload.

```bash
sudo profiles list
```

--------------------------------

### Execute psql using full path

Source: https://workbrew.com/docs/how-to-configure-postgresql-for-local-development

Command to run psql when it is not available in the system PATH due to Homebrew's keg-only installation.

```bash
/opt/homebrew/opt/postgresql@18/bin/psql -d postgres
```

--------------------------------

### Configure Corepack Installation Directory

Source: https://workbrew.com/docs/troubleshooting

Direct corepack to use a user-writable directory for symlinks.

```bash
corepack enable --install-directory ~/bin
```

--------------------------------

### Detect Homebrew installation via shell script

Source: https://workbrew.com/docs/detect-homebrew-across-your-fleet

Checks for the brew executable in standard installation paths for Apple Silicon, Intel, and Linux systems. Returns exit code 0 if found, or 1 if not.

```bash
#!/bin/bash
# Check for Homebrew in supported installation paths.
if [[ -x "/opt/homebrew/bin/brew" ]] ||
  [[ -x "/usr/local/bin/brew" ]] ||
  [[ -x "/home/linuxbrew/.linuxbrew/bin/brew" ]]
then
  echo "Homebrew is installed."
  exit 0
else
  echo "Homebrew is not installed."
  exit 1
fi
```

--------------------------------

### Configure npm Global Directories

Source: https://workbrew.com/docs/troubleshooting

Commands to redirect npm global installations to the user's home directory to avoid permission errors.

```bash
mkdir -p ~/.npm-global/bin ~/.npm-global/lib
```

```bash
npm config set prefix '~/.npm-global'
```

```bash
export PATH="~/.npm-global/bin:$PATH"
```

--------------------------------

### Integrate Workbrew Lock with direnv

Source: https://workbrew.com/docs/workbrew-lock-beta

Automate environment setup by adding a layout function to your .envrc file.

```bash
layout_workbrew_lock() {
  export HOMEBREW_WORKBREW_LOCKFILE=1
  brew bundle check >/dev/null && eval "$(brew bundle env)"
  watch_file .Brewfile.workbrew.lock.cache.json
}

layout workbrew_lock
```

--------------------------------

### Example Error Message

Source: https://workbrew.com/docs/how-to-fix-conflicting-homebrew-wrapper-configuration-errors

The error message displayed when the Homebrew wrapper configuration is misaligned.

```text
Error: conflicting Homebrew wrapper configuration!
HOMEBREW_FORCE_BREW_WRAPPER was set to /opt/workbrew/bin/brew
but `brew` was invoked by /bin/zsh.

Ensure you run /opt/workbrew/bin/brew directly (not /opt/homebrew/bin/brew)!

Manually setting your PATH can interfere with Homebrew wrappers.
Ensure your shell configuration contains:
  eval "$(/opt/workbrew/bin/brew shellenv)"
or that /opt/workbrew/bin comes before /opt/homebrew/bin in your PATH:
  export PATH="/opt/workbrew/bin:/opt/homebrew/bin:$PATH"
```

--------------------------------

### Common Conflicting PATH Patterns

Source: https://workbrew.com/docs/how-to-fix-conflicting-homebrew-wrapper-configuration-errors

Examples of configuration lines that often cause PATH conflicts.

```bash
export PATH="/opt/homebrew/bin:$PATH"
```

```bash
eval "$(/opt/homebrew/bin/brew shellenv)"
```

```bash
path=(/opt/homebrew/bin $path)
```

--------------------------------

### Create and configure a shared application role

Source: https://workbrew.com/docs/how-to-configure-postgresql-for-local-development

Commands to create a dedicated development role and configure applications to use it, including an idempotent setup script approach.

```bash
psql -U workbrew -d postgres -c "CREATE ROLE dev WITH LOGIN SUPERUSER CREATEDB;"
```

```yaml
development:
  username: dev
```

```bash
psql -U workbrew -d postgres -c "CREATE ROLE dev WITH LOGIN SUPERUSER CREATEDB;" 2>/dev/null || true
```

--------------------------------

### Allow cask vendor domains

Source: https://workbrew.com/docs/configure-your-firewall-for-workbrew

Example of allowlisting specific vendor domains for cask downloads.

```text
dl.google.com
download.mozilla.org
```

--------------------------------

### Brew Bundle Resolution Error

Source: https://workbrew.com/docs/troubleshooting

Example of the error message displayed when a formula from a third-party Tap is referenced by short name before the Tap is installed.

```text
Error: No available formula with the name "internal-cli"
```

--------------------------------

### Example Workbrew Lock File

Source: https://workbrew.com/docs/workbrew-lock-beta

The JSON structure generated by Workbrew to lock formula versions.

```json
{
  "formulae": [
    {
      "name": "node",
      "version": "23.11.0"
    }
  ]
}
```

--------------------------------

### Add Ubuntu global compinit skip

Source: https://workbrew.com/docs/how-to-fix-zsh-errors-after-installing-workbrew

Additional configuration required for some Ubuntu environments.

```bash
skip_global_compinit=1
```

--------------------------------

### Initialize the Tap repository

Source: https://workbrew.com/docs/create-a-private-tap

Clone the repository and create the required directory structure for Homebrew formulas and casks.

```bash
git clone git@github.com:acme-corp/homebrew-internal.git
cd homebrew-internal
mkdir Formula Casks
```

--------------------------------

### Configure compinit in zprofile

Source: https://workbrew.com/docs/how-to-fix-zsh-errors-after-installing-workbrew

Add this command to ~/.zprofile to bypass insecure directory prompts.

```bash
autoload -U compinit && compinit -u
```

--------------------------------

### Configure multiple PostgreSQL versions

Source: https://workbrew.com/docs/how-to-configure-postgresql-for-local-development

Steps to stop a service, modify its port in the configuration file, and restart it to allow multiple versions to run concurrently.

```bash
brew services stop postgresql@14
```

```text
port = 5433
```

```bash
brew services start postgresql@14
```

--------------------------------

### Configure Brewfile for Versioned Formulae

Source: https://workbrew.com/docs/workbrew-lock-beta

Define a formula with a version file reference in your Brewfile.

```ruby
brew "node", version_file: ".node-version"
```

--------------------------------

### GET /workspaces/<workspace>/<resource>.json

Source: https://workbrew.com/docs/workbrew-api-pagination

Retrieves a paginated list of resources for a specific workspace.

```APIDOC
## GET /workspaces/<workspace>/<resource>.json

### Description
Retrieves a paginated list of resources. The API returns 15 items per page.

### Method
GET

### Endpoint
/workspaces/<workspace>/<resource>.json

### Parameters
#### Path Parameters
- **workspace** (string) - Required - The unique identifier of the workspace.
- **resource** (string) - Required - The resource type to list.

#### Query Parameters
- **page** (integer) - Optional - The 1-indexed page number to retrieve. Defaults to 1 if omitted.

### Response
#### Success Response (200)
- **Response Body** (array) - A JSON array of resource objects.
- **X-Total-Count** (header) - Total number of records across all pages.
- **Link** (header) - The URL of the next page in RFC 8288 format. Present on every page except the last.
```

--------------------------------

### Switch to system zsh

Source: https://workbrew.com/docs/how-to-fix-zsh-errors-after-installing-workbrew

Command to change the default login shell to the system zsh.

```bash
chsh -s /bin/zsh
```

--------------------------------

### Accept Xcode License via Script

Source: https://workbrew.com/docs/troubleshooting

A script to automatically accept the Xcode license, useful for MDM deployment after macOS updates.

```bash
if /usr/bin/xcrun -find xcodebuild >/dev/null 2>&1; then
  if ! /usr/bin/xcodebuild -license check >/dev/null 2>&1; then
    /usr/bin/xcodebuild -license accept
  fi
fi
```

--------------------------------

### Verify directory structure

Source: https://workbrew.com/docs/create-a-private-tap

Commands to confirm the repository structure matches the requirements for Workbrew discovery.

```bash
ls -1
```

```bash
Casks
Formula
```

```bash
find . -not -path './.git/*' -not -path './.git' | sort
```

```bash
.
./Casks
./Casks/example-app.rb
./Formula
./Formula/hello-internal.rb
```

--------------------------------

### Identify function definition errors

Source: https://workbrew.com/docs/how-to-fix-zsh-errors-after-installing-workbrew

Example of error messages encountered when zsh frameworks fail to load function definitions.

```text
compinit:480: compdump: function definition file not found
is-at-least: function definition file not found
add-zsh-hook: function definition file not found
url-quote-magic: function definition file not found
```

--------------------------------

### Configure Shell PATH for Workbrew

Source: https://workbrew.com/docs/troubleshooting

Add this command to your shell startup configuration to ensure the correct Homebrew environment is loaded.

```bash
eval $(/opt/workbrew/bin/brew shellenv)
```

```bash
eval $(/opt/homebrew/bin/brew shellenv)
```

--------------------------------

### Homebrew untrusted tap warning

Source: https://workbrew.com/docs/allow-installation-of-packages-from-third-party-taps

Example of the warning message displayed when a user attempts to use a third-party tap that has not been granted trust.

```text
Warning: The following taps are not trusted:
  acme/tap

Homebrew is currently ignoring formulae, casks and commands from these taps because tap trust is required.
```

--------------------------------

### Fleet GitOps configuration

Source: https://workbrew.com/docs/adding-users-to-the-workbrewusers-group-via-mdm

Reference the script in your Fleet YAML configuration file to enable it via GitOps.

```yaml
controls:
  scripts:
    - path: scripts/add-user-to-workbrew-users.sh
```

--------------------------------

### View forbidden package error message

Source: https://workbrew.com/docs/declare-policies-to-block-software-packages

This is the error message displayed to end users when they attempt to install a package restricted by a Workbrew policy.

```text
$ brew install [package]
...
Error: The installation of [package] was forbidden by your Workbrew administrator
in `HOMEBREW_FORBIDDEN_FORMULAE`.
Reach out to john.doe@example.com for assistance..
```

--------------------------------

### Reference third-party formulae with fully-qualified names

Source: https://workbrew.com/docs/include-third-party-tap-formulae-in-default-packages

Use the full user/repo/name syntax for formulae from third-party Taps to ensure explicit resolution.

```ruby
tap "acme/tools"
brew "acme/tools/internal-cli"
```

--------------------------------

### Create a role matching the OS username

Source: https://workbrew.com/docs/how-to-configure-postgresql-for-local-development

Command to create a PostgreSQL role that matches the current system user's name.

```bash
psql -U workbrew -d postgres -c "CREATE ROLE \"$(whoami)\" WITH LOGIN SUPERUSER CREATEDB;"
```

--------------------------------

### Inspect git credential configuration

Source: https://workbrew.com/docs/how-workbrew-authenticates-private-taps

Use this command to identify where credential helpers are configured, which helps troubleshoot conflicts during Homebrew operations.

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

--------------------------------

### Use Strategy in Formula

Source: https://workbrew.com/docs/authenticate-private-formula-artifacts

Apply the custom download strategy to a Homebrew formula, ensuring version is defined before the URL.

```ruby
class YourApp < Formula
  version "1.2.0"
  sha256 "..."

  url "https://github.com/your-org/your-private-repo/releases/download/#{version}/your-app-#{version}.tar.gz",
      using: GitHubReleaseAssetDownloadStrategy

  def install
    # ...
  end
end
```

--------------------------------

### Workbrew sudoers configuration

Source: https://workbrew.com/docs/configure-endpoint-privilege-management-for-workbrew

The default sudoers rule added by Workbrew at /etc/sudoers.d/workbrew.

```text
_workbrewd ALL=(root) NOPASSWD:ALL
```

--------------------------------

### Use Strategy in Cask

Source: https://workbrew.com/docs/authenticate-private-formula-artifacts

Apply the custom download strategy to a Homebrew cask using the using parameter.

```ruby
cask "your-app" do
  version "1.2.0"
  sha256 "..."

  url "https://github.com/your-org/your-private-repo/releases/download/#{version}/your-app-#{version}.zip",
      using: GitHubReleaseAssetDownloadStrategy

  # ...
end
```

--------------------------------

### Commit and push changes

Source: https://workbrew.com/docs/create-a-private-tap

Stage, commit, and push the new formula and cask files to the default branch.

```bash
git add Formula/hello-internal.rb Casks/example-app.rb
git commit -m "Add hello-internal formula and example-app cask"
git push origin main
```

--------------------------------

### Initialize Workbrew Lock for NodeJS

Source: https://workbrew.com/docs/workbrew-lock-beta

Commands to add a formula to the Brewfile and commit the resulting lock file to version control.

```bash
# First, install and setup Workbrew on the Device
# Second, create HOMEBREW_WORKBREW_LOCKFILE=1 Brew Configuration in the Workbrew Console
$ brew bundle add node
$ brew bundle install
$ git add Brewfile Brewfile.workbrew.lock.json
$ git commit -m "Add Brewfile and Workbrew Lock"
$ brew bundle exec -- which node
```

--------------------------------

### Locate Intune management logs

Source: https://workbrew.com/docs/adding-users-to-the-workbrewusers-group-via-mdm

Path to the directory containing Intune management extension logs for troubleshooting script execution failures.

```text
/Library/Logs/Microsoft/Intune/
```

--------------------------------

### Deploy PPPC configuration profile

Source: https://workbrew.com/docs/preserve-app-settings-during-cask-upgrades

This XML profile grants the Workbrew Agent the required permissions. Ensure you replace the PayloadUUID and PayloadIdentifier suffix with unique values before deployment.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
	<dict>
		<key>PayloadContent</key>
		<array>
			<dict>
				<key>PayloadDisplayName</key>
				<string>Privacy Preferences Policy Control</string>
				<key>PayloadIdentifier</key>
				<string>com.apple.TCC.configuration-profile-policy.A1B2C3D4-E5F6-7890-ABCD-EF1234567890</string>
				<key>PayloadType</key>
				<string>com.apple.TCC.configuration-profile-policy</string>
				<key>PayloadUUID</key>
				<string>A1B2C3D4-E5F6-7890-ABCD-EF1234567890</string>
				<key>PayloadVersion</key>
				<integer>1</integer>
				<key>Services</key>
				<dict>
					<key>SystemPolicyAllFiles</key>
					<array>
						<dict>
							<key>Allowed</key>
							<true/>
							<key>CodeRequirement</key>
							<string>identifier "com.workbrew.workbrew-agent" and anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = "676JW3JDLF"</string>
							<key>Identifier</key>
							<string>/opt/workbrew/bin/brew</string>
							<key>IdentifierType</key>
							<string>path</string>
							<key>StaticCode</key>
							<false/>
						</dict>
					</array>
					<key>SystemPolicyAppBundles</key>
					<array>
						<dict>
							<key>Allowed</key>
							<true/>
							<key>CodeRequirement</key>
							<string>identifier "com.workbrew.workbrew-agent" and anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = "676JW3JDLF"</string>
							<key>Identifier</key>
							<string>/opt/workbrew/bin/brew</string>
							<key>IdentifierType</key>
							<string>path</string>
							<key>StaticCode</key>
							<false/>
						</dict>
					</array>
				</dict>
			</dict>
		</array>
		<key>PayloadDisplayName</key>
		<string>Workbrew App Management Permission</string>
		<key>PayloadIdentifier</key>
		<string>com.workbrew.tcc-permissions.F9E8D7C6-B5A4-3210-FEDC-BA9876543210</string>
		<key>PayloadScope</key>
		<string>System</string>
		<key>PayloadType</key>
		<string>Configuration</string>
		<key>PayloadUUID</key>
		<string>F9E8D7C6-B5A4-3210-FEDC-BA9876543210</string>
		<key>PayloadVersion</key>
		<integer>1</integer>
		<key>TargetDeviceType</key>
		<integer>5</integer>
	</dict>
</plist>
```

--------------------------------

### Verify Brew Location

Source: https://workbrew.com/docs/how-to-fix-conflicting-homebrew-wrapper-configuration-errors

Command to verify which brew binary is currently in use.

```bash
which brew
```

```text
/opt/workbrew/bin/brew
```

--------------------------------

### Search for Conflicting Configurations

Source: https://workbrew.com/docs/how-to-fix-conflicting-homebrew-wrapper-configuration-errors

Commands to search shell configuration files for Homebrew-related PATH modifications.

```bash
grep -n 'homebrew' ~/.zshrc
```

```bash
grep -rn 'homebrew' ~/.zprofile ~/.zshenv ~/.zlogin 2>/dev/null
```

--------------------------------

### Allow Homebrew package traffic

Source: https://workbrew.com/docs/configure-your-firewall-for-workbrew

FQDN-based allowlist rules for outbound HTTPS traffic on port 443 required for Homebrew metadata and package downloads.

```text
formulae.brew.sh
ghcr.io
github.com
*.githubusercontent.com
```

--------------------------------

### Add user to workbrew_users group using $3 parameter

Source: https://workbrew.com/docs/adding-users-to-the-workbrewusers-group-via-mdm

Use this script only for login/logout policies where the Jamf $3 parameter is reliably populated.

```bash
#!/bin/bash

# $3 is populated by Jamf with the username during login policies
USERNAME="$3"

if [ -z "$USERNAME" ]; then
    echo "Username not provided. Exiting."
    exit 1
fi

/usr/sbin/dseditgroup -o edit -a "$USERNAME" -t user workbrew_users
```

--------------------------------

### Define a formula

Source: https://workbrew.com/docs/create-a-private-tap

Create a formula file inside the Formula directory to define an internal tool.

```ruby
class HelloInternal < Formula
  desc "A simple greeting script from a private tap"
  homepage "https://github.com/acme-corp/homebrew-internal"
  url "https://github.com/acme-corp/hello-internal/releases/download/v1.0.0/hello-internal-1.0.0.tar.gz"
  sha256 "e3b0c44298fc1c149afb4c8996fb92427ae41e4649b934ca495991b7852b855"
  version "1.0.0"

  def install
    bin.install "hello-internal" => "hello-internal"
  end
end
```

--------------------------------

### Configure connection role in Rails or environment

Source: https://workbrew.com/docs/how-to-configure-postgresql-for-local-development

Methods to explicitly set the PostgreSQL username to 'workbrew' to avoid OS-based authentication failures.

```yaml
development:
  username: workbrew
```

```bash
export PGUSER=workbrew
```

--------------------------------

### Identify insecure directories

Source: https://workbrew.com/docs/how-to-fix-zsh-errors-after-installing-workbrew

The warning message displayed when zsh detects insecure directories during shell startup.

```text
zsh compinit: insecure directories and files, run compaudit for list.
Ignore insecure directories and files and continue [y] or abort compinit [n]?
```

--------------------------------

### Disable Prezto completion security check

Source: https://workbrew.com/docs/how-to-fix-zsh-errors-after-installing-workbrew

Add this to ~/.zpreztorc to allow unsafe completions in Prezto.

```bash
zstyle ':prezto:module:completion' unsafe true
```

--------------------------------

### Verify connectivity

Source: https://workbrew.com/docs/configure-your-firewall-for-workbrew

Commands to verify reachability of required endpoints; expects a 200 or 301 response.

```bash
curl -s -o /dev/null -w "%{http_code}" https://console.workbrew.com
curl -s -o /dev/null -w "%{http_code}" https://formulae.brew.sh/api/formula.json
curl -s -o /dev/null -w "%{http_code}" https://ghcr.io/v2/
curl -s -o /dev/null -w "%{http_code}" https://github.com
```
Tokens:
Raw