GitHub Actions 上で動作する Claude Code GitHub Actions は、Claude の定額プラン の中で無料で使えるようになりました 🎉
しかし、GitHub Actions 自体は無料枠はあるものの従量課金なため、何回も実行したり、長時間稼働させたりすると、お金がかかってきます。
本記事では、お持ちの Mac のリソースを使って GitHub Actions のコストを気にせず、Claude Code GitHub Actions を使いまくる方法を詳しく紹介します。
こんな人におすすめです 💁♀️
- Claude Code を使っているけど、 GitHub Actions の従量課金が気になって Claude Code GitHub Actions は使いこなせていない
- iOS / Mac App 開発などで GitHub Actions の実行環境に macOS が必要だが、 macOS の GitHub ランナーのコスト高（Linux マシンの 10 倍）が気になる
- メインの開発機やサブ機の Mac の性能リソースを持て余してしまっている
- 個人開発者で、開発のためのコストを極力、最小限に抑えたい
仕組み
ホストとなる Mac 上に作成した仮想マシン（VM）を macOS のセルフホステッドランナーとしてエフェメラル（都度まっさらな状態）に自動構築できるようにし、GitHub Actions のワークフローがそのランナーを利用することで GitHub ホステッドランナー利用による従量課金を回避し、Claude の定額プランの中であれば課金を気にせずにガンガン Claude Code GitHub Actions をぶん回せることを実現します。
ホストの Mac の環境も汚さない非常にクリーンな構築が可能なので、まずは試してみるという使い方にもピッタリです 💡
登場する技術用語の整理
本記事で登場する用語を簡単に整理しておきます 📚
（もちろん知ってるよって方は読み飛ばしてください）
-
GitHub Actions
- GitHub 上で CI/CD を実行するためのサービス。GitHub のリポジトリに対して自動的にビルドやテストを実行できる
-
GitHub ホステッドランナー (GitHub-hosted runners)
- GitHub Actions の実行環境
- GitHub が提供するホスト型ランナーで自分でマシンリソースを用意する必要なく使えるが、利用は従量課金制（無料枠あり）
-
セルフホステッドランナー (Self-hosted runners)
- GitHub Actions の実行環境を 自分で用意することができる機能
- これにより、GitHub の提供するランナーではなく、自分のマシンやサーバーで ワークフローを実行できる。GitHub Actions 自体の利用コストが無料
-
Claude Code
- Anthropic が提供する有料の CLI の AI コーディングエージェントツール。Claude Pro ($20) または Claude Max ($100 – $200) のマンスリー契約が必要
-
Claude Code GitHub Actions (Claude Code Action という表記も)
- GitHub Actions 上で Claude Code を利用してコードレビューや Issue 着手などの様々なエージェント処理を依頼できる
-
GitHub MCP サーバー (GitHub MCP Server)
- Claude Code GitHub Actions が内包している GitHub の公式 MCP (Model Context Protocol) サーバー
- GitHub Actions 上で Claude Code が、GitHub のリポジトリに対してコードレビューやコメントの追加などさまざまな処理を行うことができるようにする MCP
-
Tart Virtualization
- Mac 上で macOS / Linux の仮想マシン (VM) を簡単に作成・管理できる CLI
-
Tartelet
- Tart で作成した VM のクローンを用いて、Mac 上にエフェメラル (1 度限りの) なセルフホステッドランナーを簡単に構築できる OSS の GUI ツール
0. 必要なもの
ネットにつながる Apple Silicon の Mac 1 台があれば OK です。
- Mac (CI 上で macOS が必要なければ Linux マシンでもできますが今回は対象外です)
- Tart を動かすために、Apple Silicon (M1 以上) の Mac が必要
- 十分な空き容量（120 GB ほどあると理想ですが、数十 GB ほどでも動く方法も解説します）
- 安定したネットワーク環境
- いわゆる光回線であれば十分でしょう
- 電源供給
- 起動してさえいればバッテリー駆動でもよいでしょう
「自宅にて Mac を置きっぱなしで開発します」という方はメインマシンの空きリソースを使うで問題ありません。この場合は、自動スリープ設定を無効化しておきましょう。
「Mac をつけてるときだけ CI が動けばいいや」という方であれば、頻繁に持ち歩くような使い方をしている場合でもメインマシンでよいです。
そうでない方や、「ラップトップのバッテリー寿命が減るのが嫌だよ」という方などは、Mac mini のような据え置き型のサブマシンを用意すると良いでしょう。
（Mac mini M1 モデルは、最小構成の中古であれば 3 万円前後で購入でき、数年は現役として使える CI マシンになるので早めの初期投資としてもかなりおすすめです✨）
1. Tart のセットアップ
Homebrew を使って Tart をインストールします。
brew install cirruslabs/cli/tart
全ての手順をこの記事で説明をしますが、最新の情報は下記の公式ページを適宜参照してください。
2. macOS ランナー用の Tart VM の作成
Tart を使って macOS のランナー用の VM を作成します。
ここでは、Tart の開発元である Cirrus Labs が提供する macOS イメージテンプレートをクローンすることで、構築作業を簡略化します。
イメージテンプレートは、大きく以下のバージョンがあり、いずれも任意の macOS バージョンを選ぶことができます。
後ろに行くほどディスク容量が大きくなるため、容量を抑えたい場合は小さい構成のものを利用しつつ、自分で必要に応じて Homebrew や Xcode などをインストールするのがおすすめです。
-
macos-{:osName}-vanilla- OS イメージだけの最小構成
-
macos-{:osName}-base- vanilla に加え、 Homebrew がインストール済み
- ディスク容量は 50 GB
-
macos-{:osName}-xcode- base に加え、Xcode と Flutter がインストール済み
- ディスク容量は 120 GB
-
macos-runner:{:osName}- base に加え、Xcodes と複数バージョンの Xcode がインストール済み
- ディスク容量が 数百 GB と大きい
以下は、macOS 15 (Sequoia) の base イメージを用いて macOS ランナーを作成する例です。
tart clone ghcr.io/cirruslabs/macos-sequoia-base:latest macos-runner
このクローン作業は数十分以上かかります。
クローンが完了したら、できあがったイメージを起動し必要に応じて初期設定をしてください。
3. Tartelet のセットアップ
Tartelet を使って、Tart で作成した macOS ランナーのクローンを GitHub Actions のセルフホステッドランナーとしてエフェメラルに構築できるようにします。
Tartelet の README に従って、構築をしていけば良いのですが、上記の macOS イメージテンプレートを使った手順が載っておらず、それを使うともっと構築が簡単になるので以下に手順を示します。もちろん、最新の情報は README を参照するようにしてください。
3.1 Tartelet のインストール
リリースページから最新のリリース (Tartelet.zip) をダウンロード、解凍して ~/Applications フォルダに配置します。
3.2 Runner Scope の決定
Tartelet を起動し、GitHub のペインを開きます。
まず、Runner Scope を決め、Org Name or Owner / Repo Name を入力します。
Organization と Repository がありますが、Organization を選ぶとその Organization 内のすべての Repository でセルフホステッドランナーを使えるようにすることが可能です。
Repository を選ぶと、特定の Repository でのみセルフホステッドランナーを使えるようになります。
複数の Repository で使いたい場合は、Organization を選ぶのが良いですが、個人アカウント上に Repository を持っている場合などは、最もよく使う Repository を選ぶか、Organization 移管を行うのも良いでしょう。
3.3 GitHub App の作成と設定
Tartelet の GitHub ペインの最下部の「Create GitHub App」をクリックし、GitHub App の作成ページに移動します（ブラウザが開きます）。
必要な情報を入力します。
App Name は、 {:orgName} tartelet などが無難でしょう。
Homepage URL はなければ tartelet ( https://github.com/shapehq/tartelet ) のものや localhost など任意で構いません。
Webhook は使わないので Active のチェックをはずしてしまって良いでしょう。
Permissions は、Tartelet のアプリに表示されている scope を選択しましょう。
Organization なら、 Organization: Self-hosted runners (Read and write)を、
Repository なら、 Repository: Administration (Read and Write) と Repository: Metadata (Read-only) をチェックし、Create GitHub App ボタンで作成します。
作成できたら、GitHub App ページに記載されている App ID を Tartelet にコピー・ペーストします。
次に、該当の Organization または、Repository に GitHub App をインストールします。
最後に、Generate a private key ボタンをタップし、秘密鍵ファイル（.pem）をダウンロードします。この秘密鍵は重要なファイルなので、安全な場所に保存しましょう。
ダウンロードできたファイルを Tartelet の Private Key の欄に Select file をタップして貼り付けます。
Tartelet Wiki から引用
3.4 Tart Virtual Machine の設定
Tartelet の Virtual Machine ペインに移動します。
先ほど作った macos-runner という VM をセットします。
Number of Machines は、ホストマシンの容量と相談して好みの方を選択してください。
なお、最大が Two までなのは、Apple のライセンス上、一つの OS 内に macOS の仮想マシンを 2 台までしか保有することができないからです（3 台以上追加しようとすると、Virtualization Framework がエラーを返すようです）。
SSH 設定は、macOS イメージテンプレートのデフォルトである、id: admin, pass: admin をセットします。
これで Tartelet の設定は完了です。
Tartelet の Wiki には、マシン側の設定が色々書いてありますが、macOS イメージテンプレートがすでにほとんどの設定をやってくれているのでそれらをほとんどすっ飛ばすことができました。
3.5 Tartelet を開始する
実は、設定画面には Start がなく、Tartelet 本体はメニューバーにあります。
メニューバーのモニタのようなアイコンをタップすると Start という欄が出てくるのでタップして開始します。
すると、Tart が設定した台数分、指定した VM のクローンとして起動しはじめ、勝手に新しいセルフホステッドランナーとして登録しはじめます。
Terminal 上でランナーが建て終えた旨のログが出たら、GitHub 上の Organization または Repository の Settings > Actions > Runners にセルフホステッドランナーが表示されるはずです。
ちなみに、Tartelet はランナーが使用済みになると勝手にランナーを停止し VM も削除してくれ、さらに次に備えて VM をクローンしなおし、ランナーを再構築してくれます。
つまり、ワークフロー上でどんなに環境を汚しても、何も害がないという世界を自動でシームレスに実現してくれます。非常に便利ですね！
Tartelet を終了するには・・・
ちなみに終了する場合ですが、まずメニューバーの Tartelet から Stop をタップします。
ただし、これだけでは止まらず、Tart VM 内のターミナルを Ctrl + C で中断し、Tart VM のウインドウを閉じます。
これで、Tartelet の表示が Start に変わったら終了できたということになります。
（紛らわしいので、Stop を押したら Tart も閉じてほしいですね・・・）
これを行うと、GitHub 上からも Runners は見えなくなるはずです。
※ たまに、停止処理が正しくされずに残ってしまう場合があるので、その場合は GitHub 上から手動で削除しましょう
4. Claude Code GitHub Actions のワークフローのセットアップ
※ ここからは、ホストの Mac で行わなくてもよく、普段開発している Mac で作業してください
4.1 Claude Code 用の GitHub App の作成
Claude Code を GitHub 上でのイベントをトリガーにして動かすために、GitHub Actions ワークフローを構築していきます。
Claude Code GitHub Actions のセットアップは、構築したいリポジトリ上で Claude Code の /install-github-app を実行するだけで、あとは勝手に追加してくれます。
/install-github-app
╭──────────────────────────────────────────────────────────────────────╮
│ Install GitHub App │
│ Select GitHub repository │
│ │
│ > Use current repository: org name>/repo name> │
│ │
│ Enter a different repository │
│ │
╰──────────────────────────────────────────────────────────────────────╯
↑/↓ to select · Enter to continue
Use current repository を選択するとブラウザが開き、GitHub App のインストール画面になるので、Install をタップします。（すでにインストール済みの方は Configure をタップします）
インストールしたい Organization を選択し、インストールが完了すると、ブラウザページが閉じるので Claude Code に戻って Enter をタップします。
╭───────────────────────────────────────────────────────────────────────────╮
│ Install the Claude GitHub App │
│ │
│ Opening browser to install the Claude GitHub App… │
│ │
│ If your browser doesn't open automatically, visit: │
│ │
│ https://github.com/apps/claude │
│ │
│ Please install the app for repository: ruwatana/buckett │
│ │
│ Important: Make sure to grant access to this specific repository. │
│ │
│ Press Enter once you've installed the app… │
│ │
│ Having trouble? See manual setup instructions at: │
│ https://github.com/anthropics/claude-code-action/
╰───────────────────────────────────────────────────────────────────────────╯
4.2 Claude Code GitHub Actions のワークフローテンプレートの作成
GitHub ワークフローのインストールに関するダイアログが出るので、必要なものを選択しましょう。
ここでは、issue や PR で具体指示を送ることができる @Claude Code と、PR 提出時に自動でコードレビューを行ってくれる Claude Code Review をどちらも選択します。
╭───────────────────────────────────────────────────────────────────────────╮
│ Select GitHub workflows to install │
│ We'll create a workflow file in your repository for each one you select. │
│ │
│ ✓ @Claude Code │
│ Tag @claude in issues and PR comments │
│ │
│ ✓ Claude Code Review │
│ Automated code review on new PRs │
╰───────────────────────────────────────────────────────────────────────────╯
↑↓ Navigate · Space to toggle · Enter to confirm
どの API key を使うかを聞かれますが、ここは定額内で使いたい方は必ず long-lived token with your Claude subscription を選択しましょう。
new API key を選択してしまうと、Claude Code GitHub Actions の利用が従量課金になってしまうようなので注意です。
╭───────────────────────────────────────────────────────────────────────────╮
│ Install GitHub App │
│ Choose API key │
│ │
│ > Create a long-lived token with your Claude subscription │
│ │
│ Enter a new API key │
│ │
╰───────────────────────────────────────────────────────────────────────────╯
↑/↓ to select · Enter to continue
Enter を押すと、再度ブラウザページへリダイレクトするので承認するをタップします。
しばらくするとリダイレクトし、GitHub の Pull Request 作成画面に遷移します。
差分を見ると、必要なワークフローが作成されていることがわかると思います。
また、 CLAUDE_CODE_OAUTH_TOKEN という GitHub Actions 用の Repository Secrets が生成されます。
下記の URL にアクセスすると生成されていることが確認できるはずです。https://github.com/{:orgName}/{:repoName}/settings/secrets/actions
まだ Pull Request は作成せず、一度ローカルでの作業に戻ります。
4.2 Claude Code GitHub Actions のワークフローをセルフホステッドランナー利用に変更する
GitHub に push された branch を checkout します
git fetch
git checkout -b add-claude-github-actions-id>
Claude Code によって自動で生成されたすべてのワークフローは、デフォルトでは GitHub ランナーを利用する記述になっているので、Tartelet で作成されるランナーが利用されるようにラベルを変更します。
特定のランナーで動かしたいなどが出た場合は、label を複数定義すると良いでしょう。
（例: runs-on: [self-hosted, macOS, ARM64, tartelet, ...]）
.github/workflows/claude-code-review.yml
- runs-on: ubuntu-latest
+ runs-on: self-hosted
変更を commit / push します。
git add .github/workflows
git commit -m "use Self-hosted runner on claude code workflows"
4.3 Claude Code GitHub Actions のワークフローで GitHub MCP サーバーが使えるようにする
Claude Code GitHub Actions の内部アクションである claude-code-action は、デフォルトで利用している MCP サーバーをワークフロー内で起動します。
その中で、GitHub MCP サーバーという GitHub 上でのさまざまなアクションを行ってくれる MCP サーバーを立ち上げてくれますが、この実行に Docker を使っています。
しかし、先述した通りで Tart VM 上では仮想化技術をネストで使うことがベースの技術である Apple の Virtualization Framework の制約によってできません。
そこで、GitHub MCP サーバーを独自にローカルでビルドして立ち上げる処理を追加して回避します。
GitHub MCP サーバーの GitHub リポジトリにも案内がありますが、Docker を使えない場合は Go でビルドすることでローカルに実行バイナリを出力することができるので、その処理をワークフローに追記します。
※ diff は、Claude Code のバージョンによって異なる場合があるので適宜読み替えてください
.github/workflows/claude-code-review.yml
permissions:
contents: read
- pull-requests: read
+ pull-requests: write
issues: read
id-token: write
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 1
+ - name: Setup Go
+ uses: actions/setup-go@v5
+ with:
+ go-version: "1.23"
+
+ - name: Install GitHub MCP Server
+ id: build-mcp-server
+ run: |
+ go install github.com/github/github-mcp-server/cmd/github-mcp-server@latest
+ echo "path=$(go env GOPATH)/bin/github-mcp-server" >> $GITHUB_OUTPUT
+
- name: Code Review with Claude
uses: anthropics/claude-code-action@beta
with:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+ # Claude Code Action 内で GitHub MCP サーバーを構築するが、Docker を用いるため、Self-hosted runners で構築できない
+ # 事前に Go でビルドしたローカルのものを代わりに使用するように上書きさせるための設定を追加している
+ mcp_config: |
+ {
+ "mcpServers": {
+ "github": {
+ "command": "${{ steps.build-mcp-server.outputs.path }}",
+ "args": ["stdio"],
+ "env": {
+ "GITHUB_PERSONAL_ACCESS_TOKEN": "${{ secrets.GITHUB_TOKEN }}"
+ }
+ }
+ }
+ }
...
- # allowed_tools: "Bash(npm run test),Bash(npm run lint),Bash(npm run typecheck)"
+ allowed_tools: "Bash(npm run test),Bash(npm run lint),Bash(npm run typecheck),mcp__github__create_pending_pull_request_review,mcp__github__add_comment_to_pending_review,mcp__github__submit_pending_pull_request_review,mcp__github__get_pull_request_diff"
allowed_tools に GitHub MCP サーバーの tools を追加することで、LLM がそれらを必要に応じて使ってくれるようになります。
（Claude Code Action の開発中のブランチではこれらの設定がデフォルトで追加されるような動きもありそうでした）
変更をコミットし、push します。
git add .github/workflows
git commit -m "use local GitHub MCP Server instead of docker"
git push origin add-claude-github-actions-id>
最後に、先ほどの PR 作成画面をリロードし、runs-on が書きかわった commit が反映されたことを確認し、問題がなければ Create Pull Requestをタップして PR を作成します。
4.4 Claude Code GitHub Actions のワークフローを使いやすくカスタマイズする
Claude Code がデフォルトで構築したワークフローは英語ベースになっています。
さらにいえば、Claude Code GitHub Actions のベースになっているアクションのワークフロー内に記述されているシステムプロンプトは基本的に全部英語です。
つまり、何も工夫をしないと Claude からの応答が全て英語になります。
日本語で出力してくれるように指示を追加したり、先ほど使えるようになった GitHub MCP の tool 指示を具体的に追加してリッチなことができるようにしたり、レビュー内で会話が実現できるようにするなど、追加のプロンプト指示や tool 許可をすることでユーザーのユースケースに寄り添った動作を実現できるので、ここでは具体的な変更方法までは割愛しますが、個人個人が工夫してみるのをおすすめします。
自分も、GitHub MCP サーバーと連携させることでインラインコメントを可能にしたり、対話できるようにしたりなどさまざまなカスタマイズをしています。
また、機会があればそれらの Tips も別の記事でご紹介できればと思います。
5. 動作確認
Claude Code Review を選択した場合、 PR の作成をトリガーに GitHub Actions が実行されるようになります。
しばらくすると、Claude からのコメントが PR に追加され、コードレビューをしてくれるようになったかと思います。
いかがでしたでしょうか？
以上が、Claude Code GitHub Actions を定額プランで従量課金を気にせず使いまくるためのセットアップ方法でした。
ちょっとボリューミーではありますが、一度構築するとかなり使い勝手もいいと思いますので、ぜひ活用してフィードバックいただけますと幸いです！
お読みいただきありがとうございました 🙇
Views: 0
