homebrew-formula-maintenance

Original：🇺🇸 English

Translated

Homebrew formula maintenance workflows for Python CLIs and taps, including version bumps, SHA/resource updates, testing, audits, and releases.

1installs

Sourcebobmatnyc/claude-mpm-skills

Added on2026-02-18

NPX Install

npx skill4agent add bobmatnyc/claude-mpm-skills homebrew-formula-maintenance

SKILL.md Content

View Translation Comparison →

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)

Verify the PyPI release exists and grab the sdist URL + SHA256.
Update the
```
url
```
and
```
sha256
```
in the formula.

Refresh

resource

stanzas if the formula uses

virtualenv_install_with_resources

.

Test:

brew install --build-from-source

+

brew test

+

brew audit --strict

.

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:

bash

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