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