「Claude Code を GitHub Actions で動かせる」って聞いたけど、何がどう動くのか正直ピンとこないんだよな…
設定ファイルをコピペしてみたけど、API キーとサブスクどっちで動かすのが正解？
検索すると「Claude Code」が何種類も出てきて、自分が欲しいものがどれか分からないんだけど…
こんなお悩みを、全部まとめて解消していきます。
Issue や PR に @claude とコメントすると、Claude がコードを書いて push まで済ませます。
認証は個人ならサブスク用トークン、組織なら API キー。ここが最初の分かれ道です。
理由はシンプル。OAuth トークンは発行した本人の契約に紐づくからです。
この記事でわかること
- 紛らわしい4つの「Claude Code」の見分け方
- 導入の2ルートと、つまずきやすい前提条件
- API キーとサブスクトークンの選び分け
- 2種類あるコストと、その減らし方
それでは順番に見ていきましょう。
@claude とコメントするだけで、Claude がコードを書く
Issue や PR のコメントに反応して、Claude がリポジトリ内で実際にコードを編集し、コミットを pushします。
正体は anthropics/claude-code-action という GitHub Action です。
ワークフローファイルを1枚置くだけで、こんな呼びかけが通るようになります。
@claude このIssueの内容で実装して
@claude ダッシュボードのTypeErrorを直して
@claude この認証まわり、どう実装するのが筋がいい？
返事はどこに来るんですか？
Yuu同じ Issue や PR にコメントで返ってきます。作業の進行に合わせて、そのコメントが書き換わっていきます◎
まず整理｜「Claude Code」が4つあって紛らわしい
調べるほど別物が出てきて、途中で分からなくなりました…
ここ、いちばん混乱しやすいところです。名前の近い製品が4つあります。
- claude-code-action
-
本記事の主役。ワークフローを自分で書いて使うタイプです。
- Code Review
-
ワークフロー不要。PR に自動でレビューが付きます。
- Claude Code on the web
-
ブラウザやスマホから動かすタイプです。
- Claude Agent SDK
-
GitHub の外で自動化を組むための土台。今回の Action もこの上に載っています。
見分け方はひとつだけ。ワークフローファイルを自分で置くかどうかです。
じゃあ、わざわざワークフローを書く意味ってどこにあるのかな？
Yuuトリガー・モデル・プロンプトを自分で決められる点です。定型作業を仕込みたいならこちら◎
導入する｜クイックと手動、どちらを選ぶか
共通の前提
どちらのルートでも、リポジトリの管理者権限が必要です。
導入は2ルート。タブで切り替えて、自分に合うほうを見てください。
GitHub CLI（gh）を入れて gh auth login を済ませる
対象リポジトリで claude を起動し /install-github-app を実行
用意された PR を作成してマージする
App の導入・シークレット登録・ワークフロー生成まで、まとめて面倒を見てくれます。
ここでつまずきます
クイックセットアップは gh コマンドが前提です。入っていないと成立せず、Claude Code 側が不足を検知して警告します。
Yuu実際、手元の環境には gh が無くてこのルートは選べませんでした。先に入れておくのが安全です。
最小構成のワークフロー
name: Claude Code
on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
jobs:
claude:
if: contains(github.event.comment.body, '@claude')
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
issues: write
id-token: write
actions: read
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 1
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}定型部分を除くと、意味があるのは次の4行だけです。
| 記述 | 役割 |
|---|---|
id-token: write | GitHub App 認証に必須 |
actions: read | PR の CI 結果を Claude が読める |
actions/checkout | 作業用にリポジトリを取得する |
if: | 無関係なコメントでランナーを起動させない |
if: は無くても動きますよね？
Yuu動きます。ただ全コメントでランナーが起動して、Actions の分数を無駄に食います。
YAML の地味な罠
この on: は YAML 1.1 で真偽値の true として解釈されます。GitHub 側は正しく扱うので実害はありませんが、自作スクリプトで読むと躓きます。
認証は API キーとサブスクトークン、どちらにすべきか
個人利用ならサブスクトークン、複数人・組織なら API キーです。
| ANTHROPIC_API_KEY | CLAUDE_CODE_OAUTH_TOKEN | |
|---|---|---|
| 入手先 | Claude Console | claude setup-token |
| 課金 | API 従量課金 | Claude のサブスク契約 |
| 紐づき先 | 組織・ワークスペース | 発行した個人 |
| 向いている場面 | 組織で共有 | 個人リポジトリ |
サブスク側は Pro・Max・Team・Enterprise で使えます。
チームでもサブスクトークンを共有すればお得なのかな…？
Yuuそこが落とし穴です。その人が抜けると全部止まります。組織なら API キー一択で考えて大丈夫です。
サブスクトークンを使う場合は、ワークフローの1行を差し替えます。
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
長期のシークレットを置きたくない場合は、OIDC 連携という選択肢もあります。
2つの動作モード｜待ち受けか、自動実行か
モードを指定する項目はありません。prompt を書いたかどうかで自動的に切り替わります。
| インタラクティブ | オートメーション | |
|---|---|---|
| 条件 | prompt なし | prompt あり |
| きっかけ | @claude の呼びかけ | 任意のイベント・cron |
| 結果の出先 | Issue や PR のコメント | ワークフローの実行ログ |
ログにしか出ないのは、ちょっと不便じゃないか…？
Yuuそうなんです。定期レポート用途では Actions タブから開いて読む前提になります。
誰が起動できるか
Issue や PR 起点では、書き込み権限のあるユーザーだけが起動できます。Bot は原則ブロックされます。Claude が自分で自分を呼ぶ無限ループを防ぐためです。
コストは2種類ある｜Actions 分数とトークン
費用は「GitHub Actions の実行分数」と「Claude のトークン」の2本立てです。
片方だけ見ていると、想定より請求が伸びます。
トークン側はサブスクなら気にしなくていいんですよね？
Yuuはい。ただしActions の分数は別枠で消えていきます。ここが見落とされがちです。
まず効く、地味な節約
@claudeへの依頼を具体的に書き、往復回数を減らすCLAUDE.mdを簡潔に保つ（毎回読まれます）--max-turnsで反復回数に上限を付ける- ワークフローにタイムアウトを設定する
分数そのものを消したい場合
GitHub ホストのランナーを使う限り、実行時間はそのまま分数を消費します。
ここを丸ごと外す方法が、自前サーバーをセルフホストランナーにする構成です。
Yuuジョブが長い・回数が多い人ほど効きます。逆に月数回なら、無理に構える必要はありません◎
Actions の分数を気にせず回したいなら
セルフホストランナーを置く先として、月額を固定できる VPS という選択肢があります。AI関連ツールの常時稼働用途を想定したプランもあります。
先に確認を
セルフホストランナーは自分で保守する必要があります。まずは GitHub ホストで運用し、分数が足りなくなってから検討するのが堅実です。
beta を使っている人は v1 への移行が必要
前に組んだワークフローが @beta のままなんだよな。動いてはいるけど…
差分は4点だけです。順に潰していきましょう。
| beta | v1 |
|---|---|
@beta | @v1 |
mode | 削除（自動判定になった） |
direct_prompt | prompt |
max_turns / model | claude_args の中へ |
claude_args: "--max-turns 5 --model claude-sonnet-5"
1つだけ名前が変わります
custom_instructions は同名の移行先がありません。--append-system-prompt に置き換えてください。
よくあるトラブル
- @claude と書いても反応しません
-
GitHub App の導入、シークレットの登録、コメント者の書き込み権限の3点を確認してください。
/claudeや@claude-botでは反応しません。単語として@claudeが必要です。 - Claude のコミットで CI が走りません
-
既定の
GITHUB_TOKENによるコミットでは、GitHub がワークフローを起動しない仕様です。github_tokenの指定を外し、Claude GitHub App として認証させると解決します。 - 認証エラーが出ます
-
まず手元の
claudeでそのキーが通るか試してください。切り分けが一気に楽になります。 - 定期実行が途中から動かなくなりました
-
公開リポジトリでは、60日間活動がないと GitHub 側がスケジュールを無効化します。
まとめ
導入前にここだけ確認
0 / 5 完了
まずは @claude が返事をするところまで通すのが、いちばん理解が早いです。
Yuu小さなリポジトリで1往復させてみてください。そこから先は、やりたいことが自然に見えてきます◎
※本記事にはアフィリエイトリンクを含みます。料金や仕様は変更されることがあるため、契約前に必ず公式サイトで最新情報をご確認ください。
