homebrew-workflow-expert

Homebrew Workflow Expert

Deep expertise in GitHub Actions workflows for automating Homebrew formula updates, releases, and tap management.

Surface scope: Homebrew installs plugins to the Claude Code CLI surface (~/.claude/). Claude Desktop (DXT/MCPB extensions — a different, MCP-server format) and Cowork are separate surfaces; see dist-extras and commands/dist/surfaces.md for the full model.

Reusable Workflow Pattern

The recommended approach is a centralized reusable workflow in your homebrew-tap repository.

Tap Repository Structure

homebrew-tap/
├── .github/
│   └── workflows/
│       └── update-formula.yml    # Reusable workflow
├── Formula/
│   ├── myapp.rb
│   └── othertool.rb
└── README.md

Reusable Workflow (update-formula.yml)

name: Update Formula

on:
  workflow_call:
    inputs:
      formula_name:
        required: true
        type: string
        description: 'Name of the formula to update (e.g., myapp)'
      version:
        required: true
        type: string
        description: 'New version (e.g., 1.2.3)'
      sha256:
        required: true
        type: string
        description: 'SHA256 hash of the release tarball'
      source_type:
        required: false
        type: string
        default: 'github'
        description: 'Source type: github or pypi'
      source_repo:
        required: false
        type: string
        description: 'Source repository (default: github.repository)'
      auto_merge:
        required: false
        type: boolean
        default: false
        description: 'Auto-merge the PR after creation'
    secrets:
      tap_token:
        required: true
        description: 'PAT with access to tap repository'

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout tap repository
        uses: actions/checkout@v4
        with:
          repository: YOUR-ORG/homebrew-tap
          token: ${{ secrets.tap_token }}

      - name: Update formula
        run: |
          FORMULA_FILE="Formula/${{ inputs.formula_name }}.rb"

          if [ ! -f "$FORMULA_FILE" ]; then
            echo "Error: Formula $FORMULA_FILE not found"
            exit 1
          fi

          # Update version in URL
          if [ "${{ inputs.source_type }}" = "pypi" ]; then
            # PyPI URL pattern
            sed -i "s|url \"https://files.pythonhosted.org/packages/.*/.*-[0-9.]*\.tar\.gz\"|url \"https://files.pythonhosted.org/packages/source/${FIRST_CHAR}/${{ inputs.formula_name }}/${{ inputs.formula_name }}-${{ inputs.version }}.tar.gz\"|" "$FORMULA_FILE"
          else
            # GitHub URL pattern
            SOURCE_REPO="${{ inputs.source_repo || github.repository }}"
            sed -i "s|url \"https://github.com/.*/archive/refs/tags/v[0-9.]*\.tar\.gz\"|url \"https://github.com/${SOURCE_REPO}/archive/refs/tags/v${{ inputs.version }}.tar.gz\"|" "$FORMULA_FILE"
          fi

          # Update SHA256
          sed -i "s|sha256 \"[a-f0-9]*\"|sha256 \"${{ inputs.sha256 }}\"|" "$FORMULA_FILE"

          echo "Updated $FORMULA_FILE to version ${{ inputs.version }}"
          cat "$FORMULA_FILE"

      - name: Create Pull Request
        id: create-pr
        uses: peter-evans/create-pull-request@v5
        with:
          token: ${{ secrets.tap_token }}
          commit-message: "Update ${{ inputs.formula_name }} to ${{ inputs.version }}"
          title: "Update ${{ inputs.formula_name }} to ${{ inputs.version }}"
          body: |
            Automated formula update from release workflow.

            **Changes:**
            - Version: ${{ inputs.version }}
            - SHA256: ${{ inputs.sha256 }}
            - Source: ${{ inputs.source_type }}
          branch: update-${{ inputs.formula_name }}-${{ inputs.version }}
          base: main
          delete-branch: true

      - name: Auto-merge PR
        if: inputs.auto_merge && steps.create-pr.outputs.pull-request-number
        env:
          GH_TOKEN: ${{ secrets.tap_token }}
        run: |
          gh pr merge ${{ steps.create-pr.outputs.pull-request-number }} \
            --repo YOUR-ORG/homebrew-tap \
            --merge \
            --delete-branch