自作CLIツールをbrew installで配布する方法【GoReleaser自動化付き】

ツール

はじめに

自作のCLIツールを作ったとき、配布方法に悩んだことはありませんか？

「GitHubのReleasesからダウンロードして、パスを通して…」という手順を毎回説明するのは面倒ですよね。

そこで Homebrew Tap を使えば、ユーザーは以下のコマンドだけでインストールできるようになります：

brew tap your-name/tap
brew install your-name/tap/your-tool

この記事では、自作CLIツールを brew install で配布できるようにするまでの手順を、初心者向けに解説します。

全体像

まず、Homebrew Tapの仕組みを理解しましょう。

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  ツールの       │     │  GitHub         │     │  homebrew-tap   │
│  リポジトリ     │ ──▶ │  Releases       │ ◀── │  リポジトリ     │
│  (ソースコード) │     │  (バイナリ)     │     │  (Formulaファイル)│
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                               brew tap & install
  1. ツールのリポジトリでリリースを作成し、バイナリをアップロード
  2. homebrew-tapリポジトリにFormulaファイルを配置
  3. ユーザーは brew tap と brew install でインストール

Step 1: homebrew-tapリポジトリを作る

GitHubに homebrew-tap という名前のリポジトリを作成します。

ポイント: リポジトリ名は必ず homebrew- で始める必要があります。こうすることで brew tap your-name/tap のように短い名前でtapできます。

ディレクトリ構成

homebrew-tap/
├── Formula/
│   └── your-tool.rb    # Formulaファイル
└── README.md

README.mdの例

# Homebrew Tap

Homebrew formulae for your projects.

## Installation

```bash
brew tap your-name/tap
```

## Available Formulae

### your-tool

Your tool description here.

```bash
brew install your-name/tap/your-tool
```

Step 2: Formulaファイルを書く

Formula/your-tool.rb を作成します。以下は実際に使っている例です：

class YourTool < Formula
  desc "Your tool description"
  homepage "https://github.com/your-name/your-tool"
  license "MIT"
  version "1.0.0"

  on_macos do
    on_intel do
      url "https://github.com/your-name/your-tool/releases/download/v1.0.0/your-tool_1.0.0_darwin_amd64.tar.gz"
      sha256 "ここにsha256ハッシュ"
    end
    on_arm do
      url "https://github.com/your-name/your-tool/releases/download/v1.0.0/your-tool_1.0.0_darwin_arm64.tar.gz"
      sha256 "ここにsha256ハッシュ"
    end
  end

  on_linux do
    on_intel do
      url "https://github.com/your-name/your-tool/releases/download/v1.0.0/your-tool_1.0.0_linux_amd64.tar.gz"
      sha256 "ここにsha256ハッシュ"
    end
    on_arm do
      url "https://github.com/your-name/your-tool/releases/download/v1.0.0/your-tool_1.0.0_linux_arm64.tar.gz"
      sha256 "ここにsha256ハッシュ"
    end
  end

  def install
    bin.install "your-tool"
  end

  test do
    system "#{bin}/your-tool", "--version"
  end
end

sha256ハッシュの取得方法

リリースのtar.gzファイルをダウンロードして、以下のコマンドで取得できます：

shasum -a 256 your-tool_1.0.0_darwin_arm64.tar.gz

Step 3: GoReleaserで自動化する（推奨）

毎回手動でFormulaを更新するのは大変です。GoReleaserを使えば、リリース時に自動でhomebrew-tapを更新できます。

.goreleaser.yaml の設定

version: 2

builds:
  - id: your-tool
    main: ./cmd/your-tool
    binary: your-tool
    env:
      - CGO_ENABLED=0
    goos:
      - linux
      - darwin
    goarch:
      - amd64
      - arm64

archives:
  - id: your-tool
    formats:
      - tar.gz
    name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"

brews:
  - repository:
      owner: your-name
      name: homebrew-tap
      token: "{{ .Env.HOMEBREW_TAP_GITHUB_TOKEN }}"
    directory: Formula
    homepage: "https://github.com/your-name/your-tool"
    description: "Your tool description"
    license: "MIT"
    install: |
      bin.install "your-tool"
    test: |
      system "#{bin}/your-tool", "--version"

GitHub Actionsの設定

.github/workflows/release.yml を作成：

name: Release

on:
  push:
    tags:
      - 'v*'

permissions:
  contents: write

jobs:
  goreleaser:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod

      - name: Run GoReleaser
        uses: goreleaser/goreleaser-action@v6
        with:
          distribution: goreleaser
          version: latest
          args: release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          HOMEBREW_TAP_GITHUB_TOKEN: ${{ secrets.HOMEBREW_TAP_GITHUB_TOKEN }}

Personal Access Tokenの設定

  1. GitHubの Settings > Developer settings > Personal access tokens から新しいトークンを作成
  2. repo スコープを付与
  3. ツールのリポジトリの Settings > Secrets > Actions で HOMEBREW_TAP_GITHUB_TOKEN として登録

これで、タグをプッシュするたびに自動でhomebrew-tapが更新されます。

Step 4: 使ってみる

すべて設定できたら、ユーザーは以下のコマンドでインストールできます：

# tapを追加（初回のみ）
brew tap your-name/tap

# インストール
brew install your-name/tap/your-tool

# または一行で
brew install your-name/tap/your-tool

アップデートも簡単：

brew upgrade your-name/tap/your-tool

実際の例

私が運用しているhomebrew-tapでは、以下のツールを配布しています：

  • glowm: Mermaid対応のMarkdownビューア
  • lazyccg: AI coding session監視ダッシュボード
  • gh-attach: GitHub Issue/PRへの画像アップロードツール

atani/homebrew-tap – GitHub

まとめ

  • homebrew-tap リポジトリを作って Formula/ にFormulaファイルを置く
  • sha256ハッシュはリリースバイナリから計算
  • GoReleaserを使えば自動化できる
  • ユーザーは brew tap + brew install だけでインストール可能

自作ツールの配布、ぜひHomebrew Tapで便利にしてみてください。

関連リンク

タイトルとURLをコピーしました