/install-github-appでClaude GitHub Appを導入する手順

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

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

このコマンドが担うのは「クイックセットアップ」と呼ばれる経路です。手動でアプリをインストールし、シークレットを登録し、ワークフローファイルを自分でコピーする「手動セットアップ」も選べますが、ローカルでClaude Codeを動かしていないときや、ワークフローの中身を完全に自分で管理したいとき以外は /install-github-app のほうが手早く終わります。手動セットアップの手順や、GitHub Actions自体の仕組み(action v1・headless実行)はClaude CodeをGitHub Actionsに組み込むにまとめてあるので、ワークフローファイルの中身まで踏み込みたい場合はそちらを参照してください。本記事は /install-github-app というコマンド自体の挙動と、実行前後に何が起きるかに絞ります。

実行前に用意するもの

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

1. 対象リポジトリへのadmin権限。GitHub Appのインストールとリポジトリシークレットの追加はどちらもadmin権限を要求する操作なので、write権限だけでは途中で失敗します
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はワークフローの認証に使うシークレットを設定します。ここでの分岐は次の2パターンです。

• Claude Codeが既にAPIキーを持っている場合は、そのキーをそのまま再利用します。リポジトリに ANTHROPIC_API_KEY シークレットが既に設定されていれば、それを維持するかどうかも確認されます
• 持っていない場合は、Claudeサブスクリプションでの長期トークン発行と、APIキーの直接貼り付けのどちらかを選びます

選んだ認証方式に応じて、認証情報はリポジトリシークレットとして保存されます。APIキーなら ANTHROPIC_API_KEY、サブスクリプションのトークンなら CLAUDE_CODE_OAUTH_TOKEN という名前です。この2つの名前はワークフローファイル側の入力(anthropic_api_key / claude_code_oauth_token)と対応しているので、あとから手動でワークフローを書き換える場合もこの命名に合わせます。

GitHub Appのインストールが終わった時点で、Claude CodeはGitHub Actionsのセットアップを続けるか確認します。Skip for nowを選べば、GitHub Appだけをインストールした状態で止められます。ワークフローとシークレットの設定は、後日あらためて /install-github-app を実行すれば続きから再開できます。v2.1.187より前のバージョンではこの確認が無く、GitHub Appのインストール後は自動的にワークフロー選択へ進んでいました。

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

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

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

すでに claude.yml があるリポジトリで /install-github-app を再実行すると、Update workflow file with latest versionの選択肢が出ます。選ぶと新しいブランチにワークフローファイルの最新版をプッシュし、新規インストールと同じ流れでプルリクエストを開きます。ワークフローに自分で加えた変更を残したいなら、この上書きではなく、ファイルに直接 --comment 引数を足す手動編集を選びます。

ステップ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はリポジトリオーナーまたは組織オーナーに承認を求め、承認されるまでインストールは古い権限セットのまま動きます。

よくあるつまずき

• gh 未インストールで止まる: 実行前に gh auth login まで済ませておかないと、コマンド実行時に警告が出て先へ進めません
• admin権限が無いリポジトリで実行する: GitHub Appのインストールもシークレットの追加もadmin権限が必要な操作です。write権限だけのアカウントでは失敗します
• GitLab / Bitbucketリポジトリで実行してしまう: /install-github-app はgithub.comのリポジトリでしか動きません。git remoteがgitlab.comやbitbucket.orgを指していると、通知が出てセットアップは始まりません
• 既存の claude.yml を上書きするつもりが新規インストールと混同する: 既存ワークフローがあるリポジトリで再実行すると更新用の選択肢が出ますが、ワークフローに手を加えていた場合は上書きで消えます。カスタマイズを残したいなら手動で --comment 引数などを追記する側を選びます
• サブスクリプションのOAuthトークンを複数リポジトリで共有しようとする: CLAUDE_CODE_OAUTH_TOKEN は claude setup-token を実行した個人のサブスクリプションに紐づきます。組織で複数リポジトリに展開する場合は、組織全体への導入手順にあるとおりAPIキーを使う方が安全です

/install-github-appを再実行するとどうなるか

/install-github-app は一度実行して終わりのコマンドではなく、状態に応じて挙動が変わる点が特徴です。GitHub Appが未インストールなら新規インストールから、インストール済みで claude.yml が無ければワークフロー選択から、claude.yml が既にあれば更新確認から、それぞれ再開します。Skip for nowで一度中断しても、次に実行したときは続きの選択肢が出るため、GitHub Appのインストールとワークフローの導入を別のタイミングに分けて進められます。

削除したい場合は、/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側での削除も必要です。

まとめ

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