Homebrew Formula Maintenance

Overview

Use this workflow to keep Homebrew formulas in sync with PyPI releases for Python CLIs. The pattern in your taps is: update version + sha, refresh resource blocks when needed, run brew install/test/audit, then push the tap update (manually or via CI).

Quick Start (manual bump)

1. Verify the PyPI release exists and grab the sdist URL + SHA256.
2. Update the

   url

   and

   sha256

   in the formula.
3. Refresh

   resource

   stanzas if the formula uses

   virtualenv_install_with_resources

   .
4. Test:

   brew install --build-from-source

   +

   brew test

   +

   brew audit --strict

   .
5. Update changelog/tag and push the tap repo.

Local Scripts You Already Use

• homebrew-claude-mpm/scripts/update_formula.sh <version>

  • Verifies PyPI, updates url/sha, regenerates resources, optional brew test/audit.

• homebrew-claude-mpm/scripts/generate_resources.py

  • Emits Python dependency

    resource

    blocks from PyPI.

• homebrew-claude-mpm/scripts/test_formula.sh

  • End-to-end brew install/test/audit/style.

• mcp-vector-search/scripts/update_homebrew_formula.py

  • End-to-end tap update with

    --dry-run

    ,

    --version

    ,

    --tap-repo-path

    and

    HOMEBREW_TAP_TOKEN

    .

Standard Workflow

1. Confirm PyPI Release

• Check the sdist is available and capture URL/SHA.
• Typical command:

  curl -s https://pypi.org/pypi/<package>/<version>/json

  .

2. Update Formula URL + SHA

• Replace

  url

  and

  sha256

  in

  Formula/<name>.rb

  .
• Keep the formula version implicit via the sdist URL (your taps do this).

3. Refresh Resources (Python Virtualenv Formula)

If the formula uses

Language::Python::Virtualenv

and

virtualenv_install_with_resources

:

• Regenerate

  resource

  stanzas after dependency changes.
• Use

  generate_resources.py

  or equivalent; review output before pasting.

4. Test and Audit

Run these in the tap repo:

brew install --build-from-source ./Formula/<name>.rb
brew test <name>
brew audit --strict ./Formula/<name>.rb
brew style ./Formula/<name>.rb

5. Commit and Push

• Update

  CHANGELOG.md

  if the tap repo tracks releases.
• Commit, tag, and push as required by the tap workflow.

Formula Patterns (From Your Taps)

Full Virtualenv Formula (claude-mpm)

• include Language::Python::Virtualenv

• virtualenv_install_with_resources

• Large

  resource

  blocks to pin dependencies

• test do

  uses CLI commands like

  --version

  and subcommands

Minimal Venv Formula (mcp-vector-search)

• Create venv explicitly and

  pip install -v buildpath

• bin.install_symlink

  for CLI entrypoint
• Minimal

  test do

  uses

  --version

  and

  --help

CI Automation Pattern

Your GitHub Actions workflow for Homebrew updates follows this flow:

• Trigger on tag or

  workflow_run

  after CI succeeds.
• Run

  scripts/update_homebrew_formula.py

  .
• Require

  HOMEBREW_TAP_TOKEN

  (and optional

  HOMEBREW_TAP_REPO

  ).
• On failure, open an issue with manual update steps.

Troubleshooting

• PyPI release missing: verify tag push and publish step completed.
• SHA mismatch: re-fetch sdist SHA from PyPI JSON.
• brew audit failures: confirm dependency resource blocks match the sdist and

  python@x.y

  dependency is present.
• Install failures: verify

  python@x.y

  dependency and

  virtualenv_install_with_resources

  usage.

Related Skills

• toolchains/universal/infrastructure/github-actions

• toolchains/universal/infrastructure/docker