Claude CodeをGitHub Actionsへ連携する実務手順

結論：App・Secret・workflowを分けて準備する

Appをインストールしたのに@claudeが反応しない場合、workflowや認証の設定が未完かもしれません。反対に、動いたからといって外部コメントやPRを安全に扱えるとは限りません。接続の成否と、実行する権限の妥当性は別に確認します。

2026年11月1日に公式Claude Code GitHub Actionsと公式ActionのSecurity文書を確認しました。現行の認証方法と、外部PRを扱うときの注意を基に、既存workflowも点検できる導入手順を整理します。

連携を構成する三つの要素

接続できないときに分けて確認する対象

要素	役割	確認先
GitHub App	リポジトリ、Issue、PRへアクセスする	インストール対象と付与権限
認証用Secret	Claude APIまたは契約中のアカウントで認証する	Secret名とActionへの入力名
Actions workflow	イベント、権限、時間、実行内容を定義する	.github/workflows/の対象ファイル

公式の簡易設定はリポジトリでClaude Codeを開き、/install-github-appを実行して進めます。GitHub CLIの導入とログインも前提です。対象はgithub.comのリポジトリであり、GitLabやBitbucketのリモートへ同じ設定を当てはめません。

現在の手順では、Appの導入後にActionsの設定を続けるか選べます。そこで設定を中断した場合は、Appだけが入り、workflowとSecretが揃っていない可能性があります。もう一度設定を開くか、手動設定の各項目を確認し、Appの存在だけで導入済みと扱わないでください。

簡易設定はworkflow用のブランチをpushし、PRを作成する画面を開きます。表示された差分を読み、対象イベントと認証方法を確認してからPRを作成・マージします。導入用PRができたことと、実際のIssueで動作を確認したことを記録上も分けてください。

APIキーとサブスクリプション認証の比較

APIキーで認証する場合はANTHROPIC_API_KEYをGitHubのrepository secretへ保存し、workflowのanthropic_api_keyへ渡します。サブスクリプションのOAuthトークンを使う場合は、Secret名がCLAUDE_CODE_OAUTH_TOKEN、入力名がclaude_code_oauth_tokenです。値をYAMLへ直接書く方法ではありません。

以前の説明を基に「簡易設定はAPIキー専用」と判断しないでください。現行の公式手順は既存のAPIキーの再利用や、サブスクリプション用トークンの作成も案内します。すでにrepository secretがある場合は、意図せず認証方法を切り替えないよう、設定前後のSecret名と入力名を照らします。

API利用とサブスクリプション利用では請求や利用条件が異なります。GitHub Actionsの実行時間も別に管理します。契約プランや利用可能な認証方法は公式資料で確認し、費用の承認前に新しい方式へ切り替えません。基本の整理はClaude CodeのAPIキー設定も参照してください。

Amazon Bedrockなどのクラウド基盤を使う企業は、対応するクラウド向け設定を選びます。直接API用の例をコピーするだけでは、クラウド側の権限や認証が揃うわけではありません。まず既存の認証方式を確かめ、組織が認めた経路を維持します。

試験リポジトリで導入する8手順

1. 影響の小さいリポジトリを一つ選び、連携の目的を「Issueの調査」など一つに絞ります。停止担当と変更を確認する担当も決めます。
2. 必要な管理権限を持つ担当が、Appの対象リポジトリを選びます。全リポジトリへの導入を既定にしません。
3. APIキーかサブスクリプション認証かを決め、対応するSecretとActionの入力名を照合します。値をコメントやログへ出しません。
4. 公式のworkflow例から、必要なイベントと起動条件を選びます。既存ファイルがある場合は、独自の変更を残して差分をレビューします。
5. permissions:、時間制限、同時実行数、Claudeの実行回数などを用途に合わせて絞ります。認証とコメント権限も別に確かめます。
6. CLAUDE.mdへ対象範囲、禁止する変更、テスト方法を書きます。文章の指示だけを権限制御の代わりにしないでください。
7. 秘密情報のない小さなIssueで起動し、Actionsの実行、返答、変更ブランチ、費用、失敗時の結果を読み戻します。
8. 差分とテストを人間が確認し、必要なPRだけを作ります。ブランチ保護と必須チェックを維持してから、対象を段階的に広げます。

標準の@claude応答では変更を新しいブランチへコミットし、PR作成用リンクを提示する設計です。自動マージまで許可したと解釈しないでください。独自のworkflowで自動PR作成やマージを加えている場合は、公式の既定動作と分けて点検します。

起動できる利用者と権限の確認

公式Actionは通常、リポジトリへのwrite権限を持つ利用者を起動対象にします。allowed_non_write_usersはこの条件を緩める設定で、公式Security文書も重大なリスクを示しています。公開リポジトリで誰でも起動できる状態を、便利さだけで選ばないようにしてください。

botの許可も別です。allowed_botsに一致するbotは、通常利用者と同じリポジトリ権限チェックを受けません。ワイルドカードで広く許すと、外部のAppから届くイベントが起動につながる場合があります。信頼するbotを明示し、不要なイベントをworkflowから外します。

GitHub Appへ付与する権限、workflowのGITHUB_TOKENの権限、Claude Codeが実行できるツールは別の設定です。コメントだけの用途に、コード変更や公開の権限まで与えないようにしてください。ツールの拒否・確認・許可の整理はClaude Codeの権限設定へつながります。

外部PRを扱うときの安全確認

pull_request_targetやworkflow_runは、ベース側リポジトリのSecretsを使うため注意が必要です。信頼できないPRの先端を作業場所のルートへcheckoutしてからActionを動かす構成は避けます。公式Security文書にある、信頼するベースをルートへ置く構成などを確認してください。

Actionが一部のClaude設定ファイルをベースブランチから読み直すことも、安全の保証にはなりません。公式文書ではpackage.json、ロックファイル、Makefile、フォーマッターの設定などはPR側の内容が残ります。ベース側のフックがnpm runなどを実行すると、PRが変更した処理を起動する可能性があります。

そのため、フックの定義だけでなく、呼び出すスクリプトと設定の出所まで読みます。外部入力を扱う処理には秘密情報や広い書き込み権限を与えず、実行するツールと設定を信頼できる形で固定してください。一般的なテストを通した結果と、外部PRで安全に動くことは別の確認です。

show_full_outputは既定で無効です。有効にするとツールの出力やファイルの内容などがActionsのログへ出る可能性があります。認証失敗を調べる際も、トークンや環境変数の全表示で直そうとせず、Secret名、入力名、権限、対象イベントを先に確認します。

運用開始前のチェックリスト

• Appの対象リポジトリを限定した
• 認証方式とSecret・入力名が一致している
• 起動できる利用者とbotを確認した
• 外部PRから実行されるコードを確認した
• 時間・費用・同時実行の停止条件がある
• 変更とテストを確認する人が決まっている

レビュー用途で使う場合も、Actionが動いたという理由だけで必須チェックを省略しません。Claude Codeのコードレビューで、AIの指摘と既存テスト、人間の判断を分けて設計します。

よくある質問

GitHub Appを入れれば連携は完了ですか？

Appに加えて、認証用SecretとActions workflowが必要です。小さなIssueで実際の起動と返答まで確認してください。

APIキーなしでも設定できますか？

現行の公式手順はサブスクリプションのOAuthトークンも案内しています。契約の利用条件を確認し、対応するSecret名と入力名を使います。

Claudeが自動でマージしますか？

標準のメンション応答で自動マージまで行う設計ではありません。独自workflowの設定を確認し、人間の差分確認と必須チェックを残します。

導入相談

Miraigentの無料診断では外注業務へAIを導入する候補と、利用料・保守費・社内確認費を含めた実質削減額を整理します。GitHub連携でも、最初に任せる作業と人間が確認する範囲を定め、維持にかかる手間まで含めて判断します。