Claude CodeをGitHub Actionsに組み込む実用ガイド — claude-code-action v1とheadless実行の使い分け

はじめに

Claude CodeをGitHub Actionsに組み込む方法は大きく2系統あります。本記事では両方のパターンを整理し、用途別の使い分けと、認証・コスト・トラブルシューティングの実務ノウハウを示します。

2025-08-26にv1.0がリリースされ、それ以前のv0.xの mode: direct_prompt: allowed_tools: 構文はdeprecated(後方互換は維持されますが新規はv1を推奨)。本記事はv1構文で書いています。v0.xからの移行は公式migration guide を参照。

「PRをトリガーに会話セッションを動かす」なら公式アクション、「コマンドラインの1ショット実行を定期的に回す」ならheadless、と分けると判断しやすくなります。

認証の準備(両系統共通)

GitHub ActionsからClaude Codeを呼ぶには、Claude Code OAuth TokenかAnthropic API Keyのどちらかが必要です。

Claude Code OAuth Token(Maxプラン推奨)

Maxプラン契約があれば、月額枠の中で実行できるためAPI従量課金が走りません。発行手順:

# ローカル環境で 1 回だけ実行
claude setup-token
# ブラウザで Anthropic にログイン → トークンが端末に表示される

トークンをGitHubリポジトリのSecretsに CLAUDE_CODE_OAUTH_TOKEN として登録します。

Anthropic API Key(Pro / 個人開発)

Anthropic Console でAPI keyを発行 → Secretsに ANTHROPIC_API_KEY として登録。Proプランの場合はクレジットを別途プリペイドする運用になります。

パターン1: 公式アクション(anthropics/claude-code-action@v1)

PRコメント・Issue・workflow_dispatchを起点に、Claude Codeに「PRをレビューして」「このIssueを対応して」のような自然言語指示を渡す経路です。

最小構成(v1構文)

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]
 
permissions:
  contents: write
  pull-requests: write
 
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
 
      - uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          prompt: |
            この PR の変更を読み、コード品質と仕様準拠の観点でレビューしてください。
            Must / Want / 良い点を分けてコメントしてください。
          claude_args: |
            --max-turns 5
            --model claude-opus-4-7
          use_sticky_comment: true

重要なポイント:

• 認証は claude_code_oauth_token(Maxプラン)または anthropic_api_key(API key)。Bedrock / Vertex経由のみ permissions: id-token: write が必要(OIDC認証用)
• v1では prompt: に指示を、claude_args: にCLI引数を渡す形式。v0.xの mode: / direct_prompt: / allowed_tools: はdeprecated
• claude_args の中で --model --max-turns --allowedTools 等を指定する。引数は通常のClaude Code CLIと同じ
• use_sticky_comment: true で同じPRへの複数reviewが1つのコメントに集約される

よく使うイベント別の例

v1では起動経路を mode: で分けず、トリガーイベントと prompt: / trigger_phrase: の組み合わせで自動判定されます。@claude メンションを使うIssue / PRコメント連携は trigger_phrase を指定するだけで成立します。

ガードレール

Claude Code公式アクションはエージェントが BashやWebFetchを使うため、想定外の操作を防ぐガードレールを設けるのが定石です。

- uses: anthropics/claude-code-action@v1
  with:
    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
    prompt: |
      ...
    claude_args: |
      --allowedTools Bash,Edit,Read,Write,Grep,Glob
      --disallowedTools WebSearch
 
    # repository_dispatch のように外部 trigger を許す場合は allowed_bots を絞る
    allowed_bots: "renovate[bot],dependabot[bot]"

パターン2: Headless実行(claude --bare -p "...")

公式アクションを使わず、Bashステップ内でClaude Codeを直接呼ぶ方式です。出力をスクリプトで処理する自由度があります。

最小構成

name: Headless Claude
on:
  schedule:
    - cron: "0 0 * * *"  # 毎日 UTC 0:00
  workflow_dispatch:
 
jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Install Claude Code
        run: curl -fsSL https://claude.ai/install.sh | bash
 
      - name: Run headless query
        env:
          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
        run: |
          claude --bare -p "リポジトリの README.md を読んで、最近の変更点を 5 行でまとめて" > summary.txt
          cat summary.txt

claude --bare -p の挙動:

• --bare: Skills / Hooks / MCP / CLAUDE.md等の重い読み込みをスキップした最小ランタイムで起動(CIでは起動高速化)
• -p (--print): 1ショットで実行 → 標準出力に結果を出して終了
• 標準入力からプロンプトを渡すパターンも可: cat prompt.md | claude --bare -p

Headless実行が向く用途

会話セッションを開く必要がない、結果を標準出力で受け取る用途に最適です。

公式アクションvs Headlessの使い分け早見表

迷ったら公式アクションから始めるのが堅実です。後で「もっと自由度が欲しい」と思ったらheadlessへ降りる、という順序が多くのチームに合います。

コスト試算

GitHub Actionsのminutesはpublicリポジトリは無料、privateはplan別の枠 + 超過分 $0.008/min(Linux)。

Claude Code側のコストは:

• Maxプラン($100-200/月)経由: 月の利用枠内なら追加課金なし
• API key経由: 入出力トークン課金(Opusは高価)

サンプル試算(release-note自動生成パイプライン、1 run = 1記事):

実態としては「未処理0件 → skip」が大半で、検出のみで1.5分で終わるrunが多数。実消費はこの試算の半分程度になることが多い構成です。

よくあるトラブルシューティング

1. v0.xの mode: direct_prompt: allowed_tools: 構文を使うとdeprecated警告

v1.0(2025-08-26リリース)で構文が prompt: + claude_args: に変わっています。旧構文も後方互換で動きますが、@v1 環境ではdeprecation警告が出ます。新規workflowはv1構文で書き、既存は公式migration guide を参考に移行するのが堅実です。

2. ツール許可を絞りたい

claude_args: 内で --allowedTools / --disallowedTools を指定します。

claude_args: |
  --allowedTools Edit,Read,Write,Grep,Glob
  --disallowedTools WebSearch

3. Bedrock / Vertex経由でOIDCエラー

use_bedrock: true / use_vertex: true を使う場合はOIDC認証のため permissions: id-token: write が必要です。デフォルトのAnthropic API key / OAuth token利用時は不要です。

4. Headless実行のOAuthトークンが切れる

claude setup-token で発行したトークンの有効期限が切れた場合、claude --bare -p が認証エラーで失敗します。Secretsを再発行してください。

5. ヘッドレスでSkill / Hookが走らない

--bare フラグを付けた場合の意図的な挙動です。Skill / Hookを使いたい場合は --bare を外して claude -p "..." で起動します(起動が遅くなる代わりに、CLAUDE.md / Skills / Hooksがすべて読まれる)。

まとめ

• PR / Issue / dispatch triggerは claude-code-action@v1: prompt: + claude_args: 構文で書く
• 定期スクリプト / バッチは claude --bare -p: 標準出力で結果を受け取る自由度
• Maxプラン経由なら追加課金なし: cronで日次自動化しても枠内で収まりやすい
• OIDCはBedrock / Vertex経由のときだけ必須: 通常のAPI key / OAuth tokenなら不要
• v0.xの旧構文はdeprecated: 新規workflowはv1で書く、既存はmigration guideで移行

GitHub Actionsに組み込むことで、Claude Codeを「対話セッション」から「サービスの一機能」に格上げできます。リリースノート自動生成、PRレビュー、依存パッケージ監視、CHANGELOG更新といった定期作業を任せる構成は、本記事の2系統のいずれかでカバーできます。最初は公式アクションから始め、自由度が足りなくなったらheadlessに降りる順序が、学習コストと運用コストのバランスを取りやすい現実的な進め方です。

関連:Claude Code Routinesによるクラウド自動化とHooks実例カタログを組み合わせると、PR起点の自動化が一段深まります。