Claude GitHub Appのインストール手順 — /install-github-appで導入する

Claude GitHub Appの入れ方は2通り

Claude GitHub Appは、GitHubのリポジトリにClaudeをつなぐための公式アプリです。インストール先のページはgithub.com/apps/claudeで、GitHubの「Install」からリポジトリを選んで入れます。Claude Codeを手元で動かせるなら、/install-github-app コマンドが同じインストールに加えて、シークレットの登録とワークフローのPR作成まで進めます。

どちらの入れ方でも、対象リポジトリのadmin権限が要ります。アプリはGitHub Actions連携のほか、Code Reviewやクラウドセッションのauto-fixも共有します。インストール済みのアプリは、GitHubの設定画面の「Installed GitHub Apps」で確認できます。直接入れる場合の手順は、後半の「GitHubのページから直接インストールする場合」の節にあります。

/install-github-appでできること

/install-github-appは、Claude Codeのセッション内から実行するスラッシュコマンドです。Claude GitHub Appのインストール、認証用シークレットの登録、GitHub Actionsワークフローファイルを含むプルリクエストの作成までを、対話形式のプロンプトに答えるだけで一通り進めます。対象はgithub.comのリポジトリだけです。リポジトリのgit remoteがgitlab.comやbitbucket.orgを指している場合、コマンドはGitHub専用であることを通知します。GitLab CI/CDのドキュメントを案内して終了します(v2.1.259)。セットアップには進みません。GitLabのパイプラインからClaude Codeを動かす場合は、専用のGitLab CI/CD連携を使います。

このコマンドが担うのは「クイックセットアップ」と呼ばれる経路です。冒頭の表で手動側に当たらない場合は、/install-github-app のほうが手数が少なく済みます。

クイックセットアップが対応する認証は、Claude APIとClaudeサブスクリプションです。Amazon Bedrock・Google CloudのAgent Platform・Microsoft Foundryを使う場合は、クラウドプロバイダー向けの別手順になります。

ワークフローファイルの中身やaction v1・headless実行の仕組みはClaude CodeをGitHub Actionsに組み込むにあります。

実行前に用意するもの

/install-github-app を実行する前に、2つの前提が必要です。

1. 対象リポジトリへのadmin権限。クイックセットアップでも手動セットアップでも、admin権限が前提です
2. GitHub CLI(gh)のインストールと認証。gh auth login を済ませておく必要があります。Claude Codeは実行時に gh の有無を確認し、入っていなければ警告を出します

準備ができたら、連携したいリポジトリのディレクトリで claude を起動し、コマンドを実行します。

/install-github-app

あとはプロンプトに従うだけです。ここから先の流れを、Claude Codeが内部で何をしているかとあわせて追っていきます。

ステップ1: GitHub Appのインストールとシークレットの登録

コマンドを実行すると、Claude CodeはまずClaude GitHub App を対象リポジトリにインストールします。このアプリはClaude Code GitHub Actions専用ではなく、Code ReviewやClaude Code on the webのauto-fixなど、GitHubと連携するClaudeの機能全体が共有するアプリです。そのため許可を求められる権限には、GitHub Actions連携が使わないものも含まれます。

シークレットの作り方は、Claude Codeが既にAPIキーを持っているかどうかで分かれます。

この2つの名前はワークフローファイル側の入力(anthropic_api_key / claude_code_oauth_token)と対応しているので、あとから手動でワークフローを書き換える場合もこの命名に合わせます。

GitHub Appのインストールが終わった時点で、Claude CodeはGitHub Actionsのセットアップを続けるか確認します。Skip for nowを選べば、GitHub Appだけをインストールした状態で止められます。ワークフローとシークレットの設定は、後日あらためて /install-github-app を実行すれば続きから再開できます。

途中で止めたいときはEscキーを押します。実行中の手順は最後まで進み、後続の手順は始まりません。終了時のメッセージには、プッシュ済みのブランチや保存済みのシークレットなど、リポジトリで既に起きたことが並びます。

ステップ2: ワークフローファイルを選びプルリクエストを作る

続行を選ぶと、Claude Codeは選んだワークフローファイルをブランチに反映し、そのシークレットを使う設定を済ませた状態でGitHubにプッシュします。ブラウザには、作成前のプルリクエストが開きます。あとはプルリクエストを作成してマージするだけで、対象リポジトリで @claude 宛のメンションが機能するようになります。

レビュー用のワークフローを選んだ場合、Claudeはプルリクエストごとにレビュー結果を投稿します。問題を見つけたときはその箇所へのインラインコメント、問題が無いときは1件のサマリーコメントという使い分けです。ドラフトプルリクエストなど、一部のプルリクエストはレビュー対象から外れます。

すでに claude.yml があるリポジトリで /install-github-app を再実行すると、Update workflow file with latest versionの選択肢が出ます。選ぶと新しいブランチにワークフローファイルの最新版をプッシュし、新規インストールと同じ流れでプルリクエストを開きます。更新を見送りたいときはSkip workflow updateを選びます。

なお、--comment 引数と claude_args の行をファイルへ手で足す道もあります。これはv2.1.229より前に生成したレビューワークフローを、他の手直しを残したままPR投稿型にしたいときの選択肢です。足す内容は、公式のレビューワークフロー例にある該当行です。

ステップ3: GitHub Appの権限を確認する

GitHub Appをインストールする際、Claude GitHub Appは次の権限を要求します。

GitHubはこの権限セットを部分的に承認する仕組みを持たないため、インストール時はすべてまとめて許可することになります。Claude Code GitHub Actionsが実際に使うのはContents・Issues・Pull requestsの3つだけで、残りはCode Reviewやauto-fixなど他のClaude機能が使う権限です。組織のポリシーでこの3つ以外を許可したくない場合は、/install-github-app を使わず、Contents・Issues・Pull requestsだけを持つカスタムGitHub Appを自作してワークフローに組み込む方法があります。ただしこのカスタムAppはGitHub Actions連携専用で、Code Reviewやweb auto-fixは公式アプリを別途必要とします。

アプリが新しい権限を要求するようになった場合(たとえばActionsの権限がreadからread and writeへ変わったときなど)、GitHubはリポジトリオーナーまたは組織オーナーに承認を求め、承認されるまでインストールは古い権限セットのまま動きます。

GitHubのページから直接インストールする場合

Claude Codeを使わずに入れるときは、github.com/apps/claudeでアプリを対象リポジトリ(または組織)にインストールします。続けて次の2つを自分で済ませます。

1. リポジトリシークレットに ANTHROPIC_API_KEY(Claude Consoleで発行したAPIキー)または CLAUDE_CODE_OAUTH_TOKEN(claude setup-token で作るサブスクリプション用トークン)を登録する
2. claude-code-actionの examples/claude.yml を .github/workflows/ にコピーする

CLAUDE_CODE_OAUTH_TOKEN を使う場合は、ワークフロー内の anthropic_api_key の行を claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} に書き換えます。アプリだけ入れてもワークフローが無ければ @claude には反応しません。組織単位で入れる手順は組織全体への導入手順にあります。

サブスクリプションのトークンを複数リポジトリで共有しない

CLAUDE_CODE_OAUTH_TOKEN は claude setup-token を実行した個人のサブスクリプションに紐づきます。組織で複数リポジトリに展開する場合は、組織全体への導入手順にあるとおりAPIキーを使う方が安全です。

実行する環境で変わること

同じ /install-github-app でも、実行する場所によって表示や可否が変わります。changelogに載っている違いは次のとおりです。

• SSH接続先で実行する: サインインURLをコピーするショートカットが、コピー方法を正しく表示するようになりました。ブラウザを開けない環境では、URLがすぐ表示されます(v2.1.247)
• バックグラウンドセッションで実行する: v2.1.208でバックグラウンドセッションでは開かなくなり、v2.1.214でagent viewのセッションでは実行できるよう直りました。v2.1.216以降は、クライアントが接続されていないとき「needs input」の依頼がagent viewに残ります
• Enterpriseで forceLoginMethod を設定している: 強制するログイン方式は、install-github-app のログインにも適用されます(v2.1.212)

導入を取り消すときに戻す3か所

/install-github-app に対応する取り消しコマンドはなく、手動で3か所を戻します。.github/workflows/ から anthropics/claude-code-action を使うワークフロー(クイックセットアップなら claude.yml、レビューworkflowを選んでいれば claude-code-review.yml も)を削除し、リポジトリシークレットの ANTHROPIC_API_KEY または CLAUDE_CODE_OAUTH_TOKEN を削除し、他のClaude機能(Code Reviewやweb auto-fix)で使っていないことを確認したうえでGitHub App自体をアンインストールします。シークレットを削除してもAPIキー自体は無効化されないため、キーを完全に失効させたい場合はClaude Console側での削除も必要です。

マージ後に動かないときの確認先

PRをマージしても @claude に反応しないときは、次の点を順に見ます。

• GitHub Appが対象リポジトリにインストールされ、ワークフローが有効になっている
• APIキーまたはOAuthトークンがリポジトリシークレットに入っている
• コメントに @claude が単語として含まれている。/claude や @claude-bot では反応しない
• コメントした人がリポジトリへのwrite権限を持っている

そのうえでワークフローを疑う前に、手元で claude を起動して、APIキーまたはOAuthトークンが有効かを確かめます。

Claudeがコミットしたのに自分のCIが走らないなら、まず自分のCIのトリガーに push や pull_request など、Claudeのプッシュが生むイベントが含まれているかを見ます。含まれているのに動かないなら、ワークフローに github_token: ${{ secrets.GITHUB_TOKEN }} を渡していないか確認します。デフォルトの GITHUB_TOKEN で作られたコミットは、GitHubがワークフローを起動しません。この行を外してClaude GitHub Appとして認証させるか、カスタムAppのトークンを渡します。

コマンドの挙動が変わったバージョン

/install-github-app は、いくつかのバージョンで挙動が変わっています。手元のバージョンによって画面が違うのは、この履歴のためです。

まとめ

/install-github-app は、GitHub Appのインストール・認証シークレットの登録・ワークフローPRの作成という3つの作業を1つのコマンドにまとめたものです。実行前にadmin権限と gh auth login を済ませておけば、あとはプロンプトに従うだけで @claude メンションが動く状態まで進みます。ワークフローの挙動をCLI引数で細かく制御したい場合は、GitHub ActionsのパラメータとCLI引数を合わせて確認してください。