Homebrew Formula Release

Automate the complete release process for Homebrew formulae in the homebrew-tools tap.

When to Use This Skill

Use this skill when:

• User wants to publish a new version of a tool (e.g., "release v0.2.0 of mistral-ocr")
• User wants to create a new release after making changes to a tool
• User says "create a release", "publish new version", "bump version", etc.
• Changes have been committed to main and are ready for release

Do NOT use this skill when:

• User just wants to commit changes (use regular git workflow)
• User wants to update their local installation (use brew upgrade)
• No formula exists yet (tool needs to be added to tap first)

Prerequisites

Before running this skill, verify:

1. User is in the homebrew-tools repository directory
2. Changes are committed to the main branch
3. User has gh CLI installed and authenticated (gh auth status)
4. Formula file exists in Formula/ directory

Workflow

Step 1: Gather Information

Ask the user for required information:

# Identify the formula to release
# Example questions:
# - "Which tool are you releasing?" (e.g., mistral-ocr)
# - "What version number?" (e.g., v0.2.0, must start with 'v')
# - "Release notes / changelog?" (brief description of changes)

Validation:

• Version must follow format: v{major}.{minor}.{patch} (e.g., v0.1.1, v1.0.0)
• Formula file must exist at Formula/{tool-name}.rb
• Current directory must be a git repository

Tag Naming Convention: Since the homebrew-tools tap contains multiple tools with independent version lifecycles, use tool-specific tags:

• Format: {tool-name}-v{version}
• Example: mistral-ocr-v0.1.1, tool2-v1.0.0
• This allows each tool to have its own version history
• Alternative: Use simple v{version} tags if releasing the entire tap as a single versioned unit (less common)

Step 2: Create Git Tag and Push

# Create annotated tag with tool-specific version
git tag -a {tool-name}-v{version} -m "{tool-name} v{version}"

# Push tag to GitHub
git push origin {tool-name}-v{version}

Error Handling:

• If tag already exists: Ask user if they want to delete and recreate
• If push fails: Check git remote configuration and authentication

Step 3: Create GitHub Release

# Create release using gh CLI with tool-specific tag
gh release create {tool-name}-v{version} \
  --title "{tool-name} v{version}" \
  --notes "{release-notes}"

Example release notes format:

Fix CLI help text to show correct command name
- Update all references from 'python script.py' to 'tool-name'
- Improve error messages

Error Handling:

• If gh not installed: Provide installation instructions
• If authentication fails: Run gh auth login
• If release already exists: Ask to delete or skip

Step 4: Download Release Tarball and Compute SHA256

# Download the auto-generated tarball from GitHub using tool-specific tag
curl -L https://github.com/mhismail3/homebrew-tools/archive/refs/tags/{tool-name}-v{version}.tar.gz -o {tool-name}-v{version}.tar.gz

# Compute SHA256 checksum
shasum -a 256 {tool-name}-v{version}.tar.gz

Expected output format:

{64-character-hex-hash}  {tool-name}-v{version}.tar.gz

Important:

• Extract ONLY the hash (first 64 characters before the space)
• Store this for formula update in next step

Step 5: Update Formula File

Update the formula file at Formula/{tool-name}.rb:

Find and replace:

# OLD
url "https://github.com/mhismail3/homebrew-tools/archive/refs/tags/{tool-name}-v{old-version}.tar.gz"
sha256 "{old-sha256}"

# NEW
url "https://github.com/mhismail3/homebrew-tools/archive/refs/tags/{tool-name}-v{new-version}.tar.gz"
sha256 "{new-sha256}"

Important:

• Update BOTH the URL and SHA256
• Keep all other formula content unchanged
• Preserve exact Ruby formatting and indentation

Step 6: Clean Up and Commit

# Remove downloaded tarball
rm -f {tool-name}-v{version}.tar.gz

# Stage formula changes
git add Formula/{tool-name}.rb

# Commit with clear message
git commit -m "Bump {tool-name} to v{version}

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"

# Push to GitHub
git push

Step 7: Verify Release

After pushing, verify the release is available:

# Update Homebrew tap
brew update

# Check formula info shows new version
brew info mhismail3/tools/{tool-name}

Expected output should show:

• New version number
• Correct SHA256
• Formula is installable

Example Usage

User Request:

"Release v0.1.1 of mistral-ocr with the help text fixes"

Skill Execution:

1. Gather info:

   • Tool: mistral-ocr
   • Version: v0.1.1
   • Tag: mistral-ocr-v0.1.1
   • Notes: "Fix CLI help text to show 'mistral-ocr' instead of 'python ocr.py'"

2. Create tag:

   git tag -a mistral-ocr-v0.1.1 -m "mistral-ocr v0.1.1"
   git push origin mistral-ocr-v0.1.1
   

3. Create GitHub release:

   gh release create mistral-ocr-v0.1.1 \
     --title "mistral-ocr v0.1.1" \
     --notes "Fix CLI help text to show 'mistral-ocr' instead of 'python ocr.py'"
   

4. Get SHA256:

   curl -L https://github.com/mhismail3/homebrew-tools/archive/refs/tags/mistral-ocr-v0.1.1.tar.gz -o mistral-ocr-v0.1.1.tar.gz
   shasum -a 256 mistral-ocr-v0.1.1.tar.gz
   # Output: 64046b76c347bc1cfc69acd932725ac74ca10b776d6aa36b3795ee88a034cfd6
   

5. Update formula:

   # In Formula/mistral-ocr.rb
   url "https://github.com/mhismail3/homebrew-tools/archive/refs/tags/mistral-ocr-v0.1.1.tar.gz"
   sha256 "64046b76c347bc1cfc69acd932725ac74ca10b776d6aa36b3795ee88a034cfd6"
   

6. Commit and push:

   rm -f mistral-ocr-v0.1.1.tar.gz
   git add Formula/mistral-ocr.rb
   git commit -m "Bump mistral-ocr to v0.1.1"
   git push
   

7. Verify:

   brew update
   brew info mhismail3/tools/mistral-ocr
   

Error Recovery

Tag Already Exists

# Delete local tag
git tag -d {tool-name}-v{version}

# Delete remote tag
git push origin :refs/tags/{tool-name}-v{version}

# Recreate tag
git tag -a {tool-name}-v{version} -m "{tool-name} v{version}"
git push origin {tool-name}-v{version}

Release Already Exists

# Delete existing release
gh release delete {tool-name}-v{version} --yes

# Recreate release
gh release create {tool-name}-v{version} --title "{tool-name} v{version}" --notes "..."

Wrong SHA256

# Re-download tarball (GitHub may have cached old version)
curl -L https://github.com/mhismail3/homebrew-tools/archive/refs/tags/{tool-name}-v{version}.tar.gz -o {tool-name}-v{version}.tar.gz

# Recompute
shasum -a 256 {tool-name}-v{version}.tar.gz

Formula Update Failed

• Verify formula file path is correct
• Check Ruby syntax with ruby -c Formula/{tool-name}.rb
• Ensure URL and SHA256 are on separate lines
• Preserve exact indentation (2 spaces in Homebrew formulae)

Post-Release Checklist

After successful release, inform the user:

1. ✅ Version v{version} released to GitHub
2. ✅ Formula updated with new SHA256
3. ✅ Changes pushed to homebrew-tools repository
4. 📝 Users can now install with: brew upgrade {tool-name}
5. 📝 New installations will automatically get v{version}

Notes

• Do NOT include steps for updating the user's local installation - they can do that separately with brew upgrade
• Always use annotated tags (git tag -a) not lightweight tags
• SHA256 must be exactly 64 hexadecimal characters
• GitHub auto-generates release tarballs from tags - we don't manually upload anything
• The formula URL should always point to /archive/refs/tags/v{version}.tar.gz
• Users can check their tap's status with: brew tap-info mhismail3/tools

Troubleshooting

"gh: command not found"

# Install GitHub CLI
brew install gh

# Authenticate
gh auth login

"permission denied" on git push

# Check authentication
gh auth status

# Or check SSH keys
ssh -T git@github.com

Formula won't install after update

# Test formula syntax
brew audit --strict mhismail3/tools/{tool-name}

# Try installing from source
brew install --build-from-source mhismail3/tools/{tool-name}

SHA256 mismatch during user installation

• Verify the SHA256 was computed from the correct tarball
• Ensure GitHub release was created successfully
• Check that the tag points to the correct commit
• Re-download the tarball and recompute SHA256