「Claude Code を GitHub Actions で動かせる」って聞いたけど、何がどう動くのか正直ピンとこないんだよな…
設定ファイルをコピペしてみたけど、API キーとサブスクどっちで動かすのが正解？
検索すると「Claude Code」が何種類も出てきて、自分が欲しいものがどれか分からないんだけど…
Claude CodeをGitHub Actionsで動かすには、GitHub App・認証情報・ワークフローの3点を接続します。コメントがあっても、起動条件や権限が一致しなければ処理は始まりません。まず検証用リポジトリの小さなIssueで起動と結果を確認し、費用・実行時間・権限を管理してから定型作業へ広げましょう。
設定したIssueやPRのイベントでClaude Codeを起動し、調査・修正・レビューを依頼できます。コード変更やpushが行われるかは、依頼内容とワークフローの権限・設定によります。最初は小さな変更で動作を確認しましょう。
認証はAPIキーか、Claudeの契約に紐づくOAuthトークンを選びます。個人の検証と、組織で長く共有する自動化では、資格情報の管理者と費用の扱いを分けて考えてください。
理由はシンプル。OAuth トークンは発行した本人の契約に紐づくからです。
この記事でわかること
- 紛らわしい4つの「Claude Code」の見分け方
- 導入の2ルートと、つまずきやすい前提条件
- API キーとサブスクトークンの選び分け
- 2種類あるコストと、その減らし方
それでは順番に見ていきましょう。
@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 キーとサブスクトークン、どちらにすべきか
個人の試行では利用中の契約と管理しやすさから選びます。組織で複数リポジトリへ共有する資格情報は、個人の契約に紐づくOAuthトークンではなく、APIキーや対応する組織向け認証を検討します。
| ANTHROPIC_API_KEY | CLAUDE_CODE_OAUTH_TOKEN | |
|---|---|---|
| 入手先 | Claude Console | claude setup-token |
| 課金 | API 従量課金 | Claude のサブスク契約 |
| 紐づき先 | 組織・ワークスペース | 発行した個人 |
| 向いている場面 | 組織で共有 | 個人リポジトリ |
サブスク側は Pro・Max・Team・Enterprise で使えます。
チームでもサブスクトークンを共有すればお得なのかな…？
YuuOAuthトークンは発行者の契約に紐づきます。組織の共通基盤にするなら、退職・契約変更・権限変更時の扱いまで決めましょう。公式ガイドは共有SecretにはAPIキーを案内し、長期Secretを避ける方法としてOIDCも説明しています。
サブスクトークンを使う場合は、ワークフローの1行を差し替えます。
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
長期のシークレットを置きたくない場合は、OIDC 連携という選択肢もあります。
2つの動作モード｜待ち受けか、自動実行か
モードを指定する項目はありません。prompt を書いたかどうかで自動的に切り替わります。
| インタラクティブ | オートメーション | |
|---|---|---|
| 条件 | prompt なし | prompt あり |
| きっかけ | @claude の呼びかけ | 任意のイベント・cron |
| 結果の出先 | Issue や PR のコメント | ワークフローの実行ログ |
ログにしか出ないのは、ちょっと不便じゃないか…？
Yuu出力先はワークフローとバージョンで確認します。現行の公式レビュー設定はPRへのコメントに対応しています。古い設定ではログだけに出る場合があるため、公式のレビュー設定・更新手順と照合してください。
誰が起動できるか
Issue や PR 起点では、書き込み権限のあるユーザーだけが起動できます。Bot は原則ブロックされます。Claude が自分で自分を呼ぶ無限ループを防ぐためです。
コストは2種類ある｜Actions 分数とトークン
費用は「GitHub Actions の実行分数」と「Claude のトークン」の2本立てです。
片方だけ見ていると、想定より請求が伸びます。
トークン側はサブスクなら気にしなくていいんですよね？
YuuOAuth認証ではAPI従量課金の代わりに、Claudeの契約側の利用枠を使います。無制限という意味ではありません。GitHub Actionsの実行分数と、Claude側の利用状況を両方確認してください。
まず効く、地味な節約
@claudeへの依頼を具体的に書き、往復回数を減らすCLAUDE.mdを簡潔に保つ（毎回読まれます）--max-turnsで反復回数に上限を付ける- ワークフローにタイムアウトを設定する
分数そのものを消したい場合
GitHub ホストのランナーを使う限り、実行時間はそのまま分数を消費します。
セルフホストランナーを選ぶ際は、実行分数の比較にサーバーと保守の費用も加えます。たとえば月の実行量が少なければ、常時用意するサーバーの管理負担が上回る場合もあります。OS更新・監視・アクセス権・停止時の復旧を誰が担うかまで整理してから、GitHub側の現行条件と比較してください。
Yuuジョブが長い・回数が多い人ほど効きます。逆に月数回なら、無理に構える必要はありません◎
セルフホストランナーが必要な場合に比較する
まずGitHubの実行条件と費用を確認します。VPSへランナーを置く場合は、パッチ適用・権限管理・ジョブの隔離も自分で運用する前提で、構成と総費用を比較しましょう。
公式サイトで料金・利用条件を確認
利用前にGitHubホストランナーで足りる場合、VPSの追加契約は不要です。
先に確認を
セルフホストランナーは自分で保守する必要があります。まずは 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件では、コメント→Action起動→出力や差分→テストまでを確認してください。失敗したらログで認証・権限・起動条件を切り分けます。動くことを確かめた後に最大実行時間と並列数を決め、手元での分担が合う仕事はAgent Teamsの運用と比較しましょう。
※本記事にはアフィリエイトリンクを含みます。料金や仕様は変更されることがあるため、契約前に必ず公式サイトで最新情報をご確認ください。
