Claude Code GitHub Actionsの設定手順と動かない時の確認点

Claude Code GitHub Actionsは、anthropics/claude-code-actionというGitHub Actionをワークフローに置き、IssueやPull Requestのコメントで@claudeと書くとClaude Codeが解析・実装・pushまで行う仕組みです。設定はClaude Codeで/install-github-appを実行するクイック設定か、GitHub Appの導入・シークレット登録・ワークフローファイルのコピーを自分で行う手動設定のどちらかで、いずれもリポジトリの管理者権限が必要です。設定が終わったら、IssueかPRのコメントに@claudeと書いて設定の成功を確認します。

Claude Code GitHub Actionsで何ができ、似た名前の機能とどう違うのか？

@claudeのメンションに応じて動くほか、任意のGitHubイベントを起点にプロンプトを自動実行することもできます。どちらになるかはワークフローの書き方で自動的に決まります。

モード	条件	結果の出る場所
対話モード	ワークフローに`prompt`入力が無い	起点のIssueやPRへのコメント
自動化モード	`prompt`入力がある	既定ではワークフローの実行ログ

ワークフローを書かずに全PRを自動レビューする「Code Review」は名前が似た別機能で、この記事はワークフローファイルで設定するclaude-code-actionだけを扱います。ローカルのgit操作やMCP経由の連携も含めて方法を選びたい場合は、Claude Code GitHub連携の3つの方法で比較しています。GitLabを使っている場合はClaude Code GitLab CI/CDを参照してください。

設定を始める前に何を用意すればよいか？

確認しておくものは3つです。

対象リポジトリの管理者権限の確認。クイック設定でも手動設定でも必要です。
リモートがgithub.comであること。/install-github-appはgithub.comのリポジトリでだけ動き、gitlab.comやbitbucket.orgの場合は通知を出して終了します。
認証方式の選択。APIキーかサブスクリプションのOAuthトークンのどちらかをリポジトリのシークレットに置きます。

認証方式	シークレット名	ワークフローの入力名	入手方法
APIキー	`ANTHROPIC_API_KEY`	`anthropic_api_key`	Claude Consoleで発行
OAuthトークン	`CLAUDE_CODE_OAUTH_TOKEN`	`claude_code_oauth_token`	ローカルで`claude setup-token`を実行（Pro・Max・Team・Enterpriseプラン）

OAuthトークンで認証すると、実行はAPI課金ではなくClaudeのサブスクリプションを使います。ただしOAuthトークンはclaude setup-tokenを実行した人のサブスクリプションに紐づくため、公式は複数リポジトリで共有するシークレットにはAPIキーを使うよう案内しています。APIキーの発行や管理はClaude Code APIキーの記事にまとめています。

/install-github-appで設定する手順は？

ローカルでClaude Codeを使っているなら、クイック設定が早道です。GitHub Appの導入、認証シークレットの登録、ワークフローを追加するPRの準備までをClaude Codeが進めます。

まずGitHub CLIを入れて認証しておきます。入っていない場合はClaude Codeが警告を出します。

gh auth login

次に、接続したいリポジトリでclaudeを起動し、コマンドを実行してプロンプトに従います。

/install-github-app

進行の流れは次のとおりです。

Claude GitHub Appがインストールされる
認証シークレットを設定する。Claude Codeが既にAPIキーを持っていればそれを再利用し、リポジトリにANTHROPIC_API_KEYがあれば残すかを尋ねる。無ければ、サブスクリプションで長期トークンを作るか、APIキーを貼り付けるかを選ぶ
選んだワークフローファイルを含むブランチがpushされ、ブラウザでPR作成画面が開く
そのPRを作成してマージすると、リポジトリで@claudeが使えるようになる

停止方法は、途中で止めたい時にEscを押します。実行中のステップは最後まで進み、終了メッセージに実行結果として既に行われた内容（pushしたブランチ、保存したシークレットなど）が出ます。GitHub Appの導入後に「Skip for now」を選ぶとAppだけ入れた状態で止まり、あとで/install-github-appを再実行すれば残りの手順を進められます。

レビュー用ワークフローを選ぶと、ClaudeはPRにインラインコメントか、問題が無ければ1件のまとめコメントを投稿します。v2.1.229より前に作ったレビュー用ワークフローは実行ログにしか書かないため、/install-github-appを再実行し、claude.ymlがある場合に出る「Update workflow file with latest version」を選んで更新します。

なお、クイック設定が対応するのはClaude APIとClaudeのサブスクリプションです。Amazon Bedrock、Google CloudのAgent Platform、Microsoft Foundryを使う場合は後述の別手順になります。

手動で設定するには何をすればよいか？

ローカルでClaude Codeを使わない場合、コマンドが失敗する場合、ワークフローファイルを自分で管理したい場合は手動設定にします。手順は3つです。

Claude GitHub Appをリポジトリにインストールする（github.com/apps/claude）。このActionが使うのはContents、Issues、Pull requestsの読み書きです。
認証シークレットを追加する。前の表のANTHROPIC_API_KEYかCLAUDE_CODE_OAUTH_TOKENのどちらかです。
claude-code-actionリポジトリのexamples/claude.ymlを.github/workflows/にコピーする。公式はこのファイルを「例ではなく動くワークフロー」と説明しており、そのままで@claudeへのメンションにANTHROPIC_API_KEYで応答します。OAuthトークンを登録した場合は、anthropic_api_keyの行を次の行に差し替えます。

claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

公式ドキュメントに載っている、@claudeに応答するワークフローの全体は次のとおりです。

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 }}

定型以外の行の意味は公式で次のように説明されています。id-token: writeはActionの既定のGitHub App認証に必要、actions: readはPRのCI結果をClaudeが読むため、actions/checkoutは作業用のリポジトリのコピーを用意するためです。ifは@claudeを含まないコメントでランナーが起動しないようにする条件で、Action自身も応答前にトリガー語を確認します。

設定後は、IssueかPRのコメントに@claudeと依頼を書いて動作を確認します。リポジトリのルートにCLAUDE.mdを置くと、コードスタイルやレビュー基準などのルールにClaudeが従います。書き方はCLAUDE.mdの書き方を参照してください。

GitHub Appにはどんな権限を渡すことになるのか？

Claude GitHub Appは、このAction、Code Review、クラウドセッションのPR自動修正など、GitHubと連携するClaudeの機能すべてで共通です。GitHub Appの権限範囲は機能ごとに分けられないため、このActionが使わない権限も含まれます。

読み書き	読み取りのみ
Actions、Checks、Contents、Discussions、Issues、Pull requests、Repository hooks、Workflows	Administration、Members、Merge queues、Metadata、Statuses

GitHubは権限の一部だけを受け入れることを認めていません。組織の方針でこのActionが使う権限だけに絞る必要がある場合は、Contents、Issues、Pull requestsだけを持つカスタムGitHub Appを作ります。ただしカスタムAppが対応するのはこのActionだけで、Code Reviewとweb版の自動修正には公式Appが必要です。

ワークフロー側のpermissionsは、公式のベストプラクティスどおり必要なものだけを与え、Claudeの変更はマージ前に人がレビューします。権限の考え方を組織のルールとして整える話はClaude Codeの運用ルールで扱っています。

誰がClaudeを起動でき、フォークからのPRではどうなるのか？

どちらのモードでも、Claudeが動き始める前にActionが起動者を2点チェックし、どちらかで弾かれると実行は失敗します。

書き込み権限: IssueとPRのイベントでは、起動したユーザーにリポジトリへの書き込み権限が必要です。書き込み権限の無い特定のユーザーを許可するには、allowed_non_write_usersを設定し、自前のgithub_tokenを渡します。scheduleのように特定のユーザーが起こさないイベントはこのチェックを通りません。
人間であること: すべてのイベントで、allowed_botsに載っていないBotの起動は拒否されます。Bot同士でClaudeを呼び合うループを防ぐためです。スケジュール実行は多くの場合cronを最後に変更したユーザーに帰属するため、それがBotならallowed_botsに加えます。

公開リポジトリでは、フォークからのPRで起動したrunにGitHubがシークレットを渡しません。そのため公式のレビュー用ワークフロー例は、同じリポジトリのブランチから出たPRでだけ動きます。

prompt入力を使う自動化モードで平文のプロンプトを渡した場合、claude_argsの--allowedToolsか、settings入力のpermissions.allowルールで許可しない限り、Claudeはシェルにも GitHub API にもアクセスできません。スケジュール実行を使う時は、GitHubがスケジュールを既定ブランチからしか実行しないこと、公開リポジトリでは60日間活動が無いとスケジュールが無効になることも押さえておきます。

@claudeに反応しない、CIが走らない時は何を確認するか？

@claudeに反応しない時は、公式のトラブルシューティングに沿って次の順に確認します。

Claude GitHub Appがそのリポジトリにインストールされているか
リポジトリでワークフローが有効になっているか
APIキーかOAuthトークンがリポジトリのシークレットに登録されているか
コメントに@claudeが単独の語として書かれているか（/claudeや@claude-botでは反応しない）
コメントしたユーザーにリポジトリへの書き込み権限があるか

5に当てはまる場合は、前の節のallowed_non_write_usersの設定を検討します。トリガー語をtrigger_phrase入力で変えている場合は、その語で書いているかも見ます。

Claudeのコミットで他のCIが走らない時は、github_tokenの渡し方を確認します。GitHubは既定のGITHUB_TOKENで作られたコミットではワークフローを起動しません。Actionにgithub_token: ${{ secrets.GITHUB_TOKEN }}を渡しているなら、その行を外してClaude GitHub Appとして認証させるか、カスタムAppのトークンを渡します。あわせて、CI側のトリガーにClaudeのpushで発生するpushやpull_requestが含まれているかも確認します。

認証エラーの時は、ワークフローを調べる前に、同じAPIキーかOAuthトークンでローカルのclaudeが動くかを確かめます。キー自体が無効なのか、ワークフローの渡し方の問題なのかがここで分かれます。

費用はどこで発生し、どう抑えるか？

1回の実行で消費するものは2種類です。

GitHub Actionsの実行時間: GitHubホストのランナーで動くため、リポジトリのActionsの分数を消費します。
APIトークン: プロンプトと応答の長さ、タスクの複雑さ、コードベースの規模に応じて消費します。OAuthトークンで認証している場合は、API課金ではなくサブスクリプションの利用枠を使います。

公式が挙げる抑え方は、依頼を具体的に書く、Issueテンプレートで文脈を渡す、毎回読まれるCLAUDE.mdを簡潔に保つ、ワークフロー単位のタイムアウトとGitHubのconcurrency制御で暴走や並列実行を抑える、claude_argsの--max-turnsで反復回数を制限する、の6点です。claude_argsにはClaude CodeのCLI引数をそのまま渡せ、公式の例は次の形です。

claude_args: "--max-turns 5 --model claude-sonnet-5 --mcp-config /path/to/config.json"

--modelを省くと、ActionはClaude Codeの既定モデルを使います。プランごとの料金の違いはClaude Codeの料金プランで扱っています。

@betaのワークフローはどう書き換えればよいか？

ワークフローがまだanthropics/claude-code-action@betaを参照しているなら、公式の手順でv1に移行します。

uses行の@betaを@v1に変える
mode入力を削除する（v1はモードを自動判定する）
direct_promptをpromptに置き換える
max_turnsやmodelなどのCLIオプションをclaude_argsに移す。custom_instructionsは同名のフラグが無く、--append-system-promptになる

入力の対応表と書き換え前後の例は、claude-code-actionリポジトリのmigration guideにあります。

組織全体に広げる時、Bedrockなどを使う時は何が変わるか？

組織に広げる時は、Claude GitHub Appを組織レベルで1回インストールし（全リポジトリか選択したリポジトリ）、認証シークレットを組織レベルのActionsシークレットに置き、ワークフローを各リポジトリに追加するか、reusable workflowとして1か所に定義して各リポジトリから呼びます。共有シークレットには、前述のとおりOAuthトークンではなくAPIキーを使います。

長期のシークレット自体を置きたくない場合は、workload identity federationを使えます。ワークフローのGitHub OIDCトークンを、Claude Consoleのサービスアカウント経由でClaude APIへのアクセスに交換する方式で、anthropic_federation_rule_idとanthropic_organization_idを入力に設定し、ワークフローにid-token: writeを与えます。

推論を自社のクラウドアカウント経由にする場合は、Amazon Bedrockならuse_bedrock: "true"、Google CloudのAgent Platformならuse_vertex: "true"、Microsoft Foundryならuse_foundry: "true"を設定します。3つともClaude APIキーではなくOIDCによるID連携で認証するため、リポジトリに静的なクラウド認証情報を置きません。各プロバイダー側の準備はClaude Code BedrockとClaude Code Vertex AIの記事で扱っています。

使わなくなったら何を消せばよいか？

ワークフロー: .github/workflows/からanthropics/claude-code-actionを使うファイルを削除します。クイック設定ならclaude.ymlと、レビュー用を選んでいればclaude-code-review.ymlです。これでActionは動かなくなります。
シークレット: ANTHROPIC_API_KEYかCLAUDE_CODE_OAUTH_TOKENをリポジトリ（組織で共有していれば組織レベルも）から削除します。シークレットを消してもキー自体は有効なままなので、APIキーを完全に無効にするにはClaude Consoleでも削除します。
GitHub App: Code Reviewやweb版の自動修正など、他のClaudeの機能で使っていない場合に限ってアンインストールします。

この記事の手順や入力名は、2026年10月時点のcode.claude.comの記述に基づいています。入力の全一覧はclaude-code-actionリポジトリのconfiguration referenceにあるため、ここに無い入力を使う時はそちらで確認してください。

チームで権限やレビューの運用ルールまで含めて導入を進めたい場合は、NO WAVEの企業研修の内容・料金も確認できます。