Homebrew Publish Plugin
Relevant source files
The following files were used as context for generating this wiki page:
- packages/plugins/plugin-brew/src/brew-core.ts
- packages/plugins/plugin-brew/src/brew-tap.ts
- plugins/pubm-plugin/skills/publish-setup/references/homebrew-setup.md
- plugins/pubm-plugin/skills/publish-setup/references/official-plugins.md
- packages/plugins/plugin-brew/package.json
- packages/plugins/plugin-brew/tests/e2e/asset-pipeline-to-formula.test.ts
The Homebrew Publish Plugin (@pubm/plugin-brew) is an official extension for the pubm ecosystem designed to automate the distribution of CLI tools via Homebrew. It manages the lifecycle of Homebrew formulae, including generation, checksum updates, and repository synchronization. This plugin is particularly essential for Rust-only projects or environments where Node.js is not present, as it allows users to install the software using standard brew install commands.
The plugin provides two primary distribution workflows: brewTap for maintaining formulae in custom user repositories (Taps) and brewCore for submitting updates to the official homebrew/homebrew-core repository. It integrates deeply with pubm's asset pipeline, ensuring that platform-specific binaries (e.g., Darwin ARM64, Linux X64) are correctly mapped to formula entries with accurate SHA256 checksums.
Sources: plugins/pubm-plugin/skills/publish-setup/references/homebrew-setup.md:3-8, packages/plugins/plugin-brew/package.json:2-6
Architecture and Components
The plugin is structured into two main modules that share a common formula manipulation engine. Both modules leverage afterRelease hooks to trigger automation once GitHub Release assets are available.
Core Modules
| Module | Purpose | Key Mechanism |
|---|---|---|
brewTap | Custom Tap management | Clones a target repository, updates the formula, and pushes changes. |
brewCore | Official core submission | Forks homebrew-core, creates a branch, and opens a Pull Request. |
Sources: packages/plugins/plugin-brew/src/brew-core.ts:12-14, packages/plugins/plugin-brew/src/brew-tap.ts:13-15, plugins/pubm-plugin/skills/publish-setup/references/official-plugins.md:73-76
Data Flow for Formula Updates
The plugin follows a specific sequence to ensure formula accuracy. It must first identify release assets, calculate their checksums, and then inject this data into the Ruby-based formula file.
The diagram above shows the logic flow from the afterRelease hook to the final publication.
Sources: packages/plugins/plugin-brew/src/brew-core.ts:110-150, packages/plugins/plugin-brew/src/brew-tap.ts:100-140
Distribution Workflows
Custom Taps (brewTap)
The brewTap function allows developers to host their own Homebrew repository. It supports two modes:
- Same-Repo: Updates a formula folder within the current project repository.
- Separate-Repo: Clones a dedicated Tap repository (e.g.,
user/homebrew-tap), updates the formula there, and pushes the changes.
If a direct git push fails (due to branch protection or permissions), the plugin automatically falls back to creating a Pull Request.
Sources: packages/plugins/plugin-brew/src/brew-tap.ts:145-180, plugins/pubm-plugin/skills/publish-setup/references/official-plugins.md:113-118
Homebrew Core (brewCore)
For popular tools, brewCore automates the PR process to the official Homebrew repository.
The sequence diagram illustrates the complex fork-and-pull workflow required for official Homebrew submissions.
Sources: packages/plugins/plugin-brew/src/brew-core.ts:130-175
Platform and Asset Matching
A critical feature of the plugin is the ability to match GitHub Release assets to the correct Homebrew platform block (e.g., on_macos or on_linux).
Default Platform Mappings
| Formula Entry | Match Condition |
|---|---|
darwin-arm64 | os === "darwin" && arch === "arm64" |
darwin-x64 | os === "darwin" && arch === "x64" |
linux-arm64 | os === "linux" && arch === "arm64" |
linux-x64 | os === "linux" && arch === "x64" |
Users can override these mappings using the assetPlatforms configuration option to handle specific ABIs like musl.
Sources: plugins/pubm-plugin/skills/publish-setup/references/homebrew-setup.md:112-120, packages/plugins/plugin-brew/tests/e2e/asset-pipeline-to-formula.test.ts:114-125
Configuration and Credentials
Plugin Options
interface BrewOptions {
formula: string; // Path to formula file (e.g., 'Formula/tool.rb')
repo?: string; // (brewTap only) URL of the tap repository
packageName?: string; // Filter for monorepo package releases
assetPlatforms?: Record<string, (asset: any) => boolean>; // Custom matchers
}
Sources: packages/plugins/plugin-brew/src/brew-core.ts:10-14, packages/plugins/plugin-brew/src/brew-tap.ts:11-15
Authentication
The plugin requires a PUBM_BREW_GITHUB_TOKEN (Personal Access Token) when running in CI mode to perform repository cloning, forking, and PR creation.
- Local Mode: Uses the
ghCLI for authentication (gh auth status). - CI Mode: Requires the
PUBM_BREW_GITHUB_TOKENto be set as a secret.
Sources: packages/plugins/plugin-brew/src/brew-core.ts:60-85, plugins/pubm-plugin/skills/publish-setup/references/homebrew-setup.md:143-148
Rollback Mechanisms
To ensure repository integrity, the plugin registers rollback actions. If the publication pipeline fails after a PR has been opened, pubm will attempt to automatically close the PR.
ctx.runtime.rollback.add({
label: `Close homebrew-core PR #${prNumber}`,
fn: async () => {
execSync(`gh pr close ${prNumber} --repo homebrew/homebrew-core`);
},
confirm: true,
});
Sources: packages/plugins/plugin-brew/src/brew-core.ts:182-195, packages/plugins/plugin-brew/src/brew-tap.ts:258-270
Summary
The Homebrew Publish Plugin provides a robust automation layer for distributing binaries through the Homebrew package manager. By handling formula generation, platform-specific asset matching, and complex Git workflows (including forking and PR management), it reduces the manual overhead of cross-platform CLI distribution. Its integration with pubm's rollback system and support for both official and custom repositories makes it a versatile tool for both established and emerging software projects.