Claude CodeとGitHubの連携方法｜3つの連携パターン・設定手順・GitHub Actionsの例【2026年版】

Claude CodeとGitHubの連携は、IssueへのコメントひとつでPR作成まで完結する「エージェント型ワークフロー」として急速に普及しています。本記事では、公式ドキュメントに基づいて3つの統合レイヤーを整理し、ブランチ戦略・権限設計・コスト管理の実践的な勘所と、見落とされがちな失敗パターンを論じます。

Claude Code × GitHubの現在地

2026年2月時点では、GitHubの公開コミットのうち4%がClaude Codeによって生成されているとSemiAnalysisは推定していた（出典：Gigazine）。同分析では2026年末に20%へ到達する可能性も示唆されています。この数字が示すのは、IDE内のコード補完の延長線上ではなく、Gitワークフロー全体への浸透です。

Claude CodeはIssueを起点にブランチ作成・実装・コミット・PR作成まで一気通貫で処理できるターミナル常駐型エージェントであり、従来の「補完ツール」とは権限モデルもリスクプロファイルも異なる（出典：Ledge.ai）。導入を検討するエンジニアや技術責任者にとって必要なのは、このアーキテクチャ上の差異を正確に把握したうえで、自チームのワークフローに合った統合設計を選択することです。

本記事では、claude code githubの連携形態を3つの統合レイヤーに整理し、ブランチ戦略・権限設計・コスト管理の実践的な勘所と、見落とされがちな失敗パターン・限界を論じます。Claude Codeの基本的な位置付けについてはClaude Codeとはを、料金体系の全体像は料金ガイドを先に参照しておくことを勧めます。

関連記事Claude Code（クロードコード）とは？できること・料金・使い方を初心者にもやさしく解説【2026年版】 ／ Claude Code 使用量を完全制御する実装ガイド【2026年版】 ／ Claude Code ログイン方法・できない時の対処法｜2026年版ガイド

claude code github連携の3つの統合レイヤー：選択基準と実装上の差異

Claude CodeとGitHubを連携させる方法は、権限モデル・自動化範囲・運用コストの観点から3つのレイヤーに整理できます。それぞれを混同したまま導入すると、権限過剰・意図しない自動コミット・コスト超過といった問題を招きます。レイヤーの選択は技術的好みではなく、チームのリスク許容度とワークフロー成熟度に基づいて判断すべきです。

レイヤー1：ローカルCLI × Gitコマンド直接実行

最もシンプルで、リスクの低い統合形態です。Claude Codeをローカル環境にインストールし（詳細はインストールガイド参照）、プロジェクトルートで起動すると、リポジトリのファイルツリー・Git履歴・差分を自動的に把握します。エンジニアが「このIssueの要件を実装してコミットまで行え」と指示すると、以下を順次実行します。

1. 関連ファイルのコンテキスト収集（git log・git diff等）
2. 実装コードの生成・既存ファイルへの書き込み
3. 設定済みのテストランナーが存在する場合はテスト実行
4. git add・git commitの実行（コミットメッセージも自動生成）

この層ではClaude CodeがGitHub APIを直接呼ばないため、Personal Access Tokenなどの追加認証は不要です。ただし、コミット署名（GPG）やpre-commitフックとの整合性は事前検証が必要であり、特にgit-secrets等のシークレット検出フックが正常動作するかは必ず確認しておきます。

Qiitaに掲載された実践事例（nakamasato「Claude Code AIコーディング開発サイクル」2026/01/18、Qiita）では、GitHub IssueでPlanを設計しArtifactとして固定してからClaude Codeに渡す手順が有効とされています。ローカルCLI利用であっても、Issueを「渡す文書」として整備する習慣が精度に直結します。

レイヤー2：GitHub Actionsへの組み込み（Claude Code Action）

公式ドキュメント（Claude Code GitHub Actions）によれば、公式アクション（検索では「claude code action」とも呼ばれる）をワークフローに組み込み、PRやIssueで @claude とメンションするだけで、コードの分析・PR作成・機能実装・バグ修正を自動実行できます。Anthropicが公式に提供する claude-code-action リポジトリを用いることで、YAML記述量を最小化した組み込みが可能です。

典型的なユースケースは次のとおりです。

• PRやIssueへの @claude メンションでコードレビューコメントを自動生成する
• Issueコメントの @claude 指示でClaude Codeが実装ブランチを作成しDraft PRを出す
• すべてのPRに自動レビューを投稿する（トリガー不要の場合はGitHub Code Review機能を参照）

セットアップ方法は2通りあります。最も簡単な方法は、ターミナルでClaudeを起動し /install-github-app コマンドを実行することだ（公式ドキュメント）。このコマンドがGitHub Appのインストールと必要なSecretsの設定をガイドします。ただし以下の点に注意が必要です。

• 実行にはリポジトリの管理者権限が必要
• GitHub Appのインストールでは、Contents・Issues・Pull requestsを含む複数の権限をまとめて許可します（一部だけを選ぶことはできません）。GitHub Actionsのアクションが使うのは、そのうちContents・Issues・Pull requestsの3つです
• /install-github-app はClaude APIのキーでもClaudeのサブスクリプションでも使えます。Amazon Bedrock・Google CloudのAgent Platform・Microsoft Foundry経由の利用者は、クラウド事業者向けの手順で設定する
• 事前にGitHub CLI（gh）を入れて gh auth login でログインしておきます。対象はgithub.comのリポジトリだけで、GitLabやBitbucketでは使えない

使うモデルは、公式ドキュメントによれば claude_args に --model を書いて指定します。指定しなければ、Claude Codeの既定のモデルが使われます。

認証の方法は2つあります。1つはClaude Consoleで発行したAPIキーを ANTHROPIC_API_KEY という名前でSecretsに登録する方法で、使った分だけAPIの従量課金になります。もう1つは、手元で claude setup-token を実行して作ったトークンを CLAUDE_CODE_OAUTH_TOKEN として登録する方法で、Pro・Max・Team・Enterpriseのサブスクリプションの利用枠で動きます。ワークフローでは、前者は anthropic_api_key、後者は claude_code_oauth_token に渡す。複数のリポジトリで共有するシークレットには、個人のサブスクリプションにひも付かないAPIキーを使うよう公式は勧めています。どちらの場合も、消費量の管理をワークフロー設計に組み込む必要があります。APIの料金体系と消費量の見積もり方についてはAPIコスト解説記事で詳述しています。

レイヤー3：MCP（Model Context Protocol）経由のGitHub統合

GitHub公式のMCPサーバーを介すことで、Claude CodeがIssue・PR・リリースノートを直接読み書きできるようになります。ローカルCLIと組み合わせると「Issueの番号を渡すだけで実装からPR作成まで自律実行するエージェントループ」を構成できます。Claude Code GitHub Actionsも Claude Agent SDK の上に構築されており、GitHub Actions以外のカスタム自動化ワークフローを構築する際の基盤として利用できます。

なお、公式ドキュメント（GitHub Enterprise Server対応ページ）によれば、GitHub MCPサーバーはGitHub Enterprise Server（GHES）では現時点で非対応であることが明記されています。GHES環境での利用を検討する場合はこの制約を事前に確認しておく必要があります。

手元のClaude CodeにGitHubのMCPサーバーをつなぐコマンドは、公式のMCPのドキュメントでは次の形で紹介されています（2026年10月13日確認。トークンは自分のものに置き換えます。この記事では実行していません）。

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

つないだあとは /mcp を実行し、サーバーが connected と表示されるかを確かめます。認証情報が誤っていると failed と表示され、401などのHTTPステータスも示されます。この方式はヘッダーにトークンを入れるため、/mcp はサインインではなく接続の確認用です。保存先は既定では自分だけ・そのプロジェクトのみ（local）で、--scope project で .mcp.json に書いてチームで共有、--scope user で全プロジェクトに使えます。

このレイヤーは自律度が最も高い分、権限設計と監視体制が不十分な状態で導入すると意図しない操作が発生するリスクも最大になります。

3つのレイヤー以外の公式のGitHub連携

公式ドキュメントは、名前の似た関連機能として次のものを挙げています。ワークフローファイルを自分で書かずに済むものもあるため、目的に合えばこちらのほうが手間は少なくなります（2026年10月13日確認）。

• Code Review：ワークフローを書かなくても、すべてのプルリクエストを自動でレビューする機能（Code Review）
• クラウドで動くClaude Code：手元のPCではなくクラウド上でセッションを動かし、GitHubのリポジトリを対象に作業させる
• Claude Agent SDK：GitHub Actions以外の場所で独自の自動化を組むための部品です。GitHub Actions用の公式アクションもこの上に作られている
• GitHub Enterprise Server：自社で運用するGitHubとつなぐ場合の対応（後述）

これらの機能は、同じClaudeのGitHub Appを共用しています。Appをインストールするときは、機能ごとに権限を選ぶことはできず、まとめて許可する形になります。GitHub Actions用のアクションが使うのは、そのうちContents・Issues・Pull requestsの3つです。

Claude Codeを使わずに、Claudeのチャット画面へGitHubのリポジトリを読ませる方法

「ClaudeとGitHubの連携」には、Claude Codeではなく、ブラウザやアプリのClaude（チャット画面）にリポジトリのファイルを読ませる使い方もあります。コードの内容について質問したい、設計の相談をしたい、という目的ならこちらで足ります。手順はAnthropic公式ヘルプのとおり（2026年10月10日確認）。

• チャットで使う：入力欄の左下の「+」から「Add from GitHub」を選び、ファイルやフォルダを選んでからメッセージを送る
• プロジェクトで使う：プロジェクトの知識（project knowledge）の右上の「+」から「GitHub」を選び、リポジトリを検索するかURLを貼って、読ませるファイルやフォルダを選びます。内容を更新するときは「Sync」を押す
• 読み込まれる範囲：指定したブランチのファイル名と中身だけです。コミット履歴やプルリクエストなどは読み込まれない
• 非公開リポジトリが出てこないとき：GitHub App側でそのリポジトリへのアクセスを許可する（組織のリポジトリは管理者の承認が必要）。シングルサインオンを必須にしている組織では、GitHubの設定画面（Applications）でClaudeに対して組織へのアクセスを許可します。接続をやり直しても解決しない

この方法はファイルを読ませるための連携で、公式ヘルプにはリポジトリへ書き込む手順は書かれていません。ブランチの作成・コミット・プルリクエストの作成まで任せたい場合は、本記事の3つのレイヤー（Claude Code）を使います。

実装後すぐ使える：コピペ可能なGitHub Actions YAMLとv1.0移行チェック

前章で紹介した3つの統合レイヤーのうち、GitHub Actions経由での自動化を選ぶ場合は、実際に動く設定ファイルの形と、2026年にリリースされたv1.0での破壊的変更を押さえておく必要があります。以下は公式リポジトリ（anthropics/claude-code-action）の仕様に基づく最小構成の実装例と、v0.x系からの移行時に必ず確認すべき変更点の対応表です。

セットアップの手順：クイックセットアップと手動セットアップ

公式ドキュメントでは、Claude Code GitHub Actionのセットアップは2通りです。どちらもリポジトリの管理者権限が必要です（2026年10月13日確認）。

• クイックセットアップ：リポジトリのフォルダで claude を起動し、/install-github-app を実行して案内に従います。Claude CodeがGitHub Appを入れ、認証用のシークレットを登録し、ワークフローのファイルを入れたブランチをpushして、GitHubをブラウザで開きます。作成待ちのプルリクエストを作ってマージすると、そのリポジトリで @claude が動くようになります
• 手動セットアップ：Claude Codeを手元で動かさない場合、コマンドが失敗した場合、ワークフローのファイルを自分で管理したい場合の方法です。次の3つを自分で行います

1. Claude GitHub App をリポジトリに入れる
2. 認証用のシークレットを追加します。APIキーなら ANTHROPIC_API_KEY、サブスクリプションなら claude setup-token で作ったトークンを CLAUDE_CODE_OAUTH_TOKEN として登録します
3. 公式リポジトリの examples/claude.yml を .github/workflows/ に置く（そのまま動くワークフローです。サブスクリプションの場合は anthropic_api_key の行を claude_code_oauth_token に変えます）

クイックセットアップの途中で止めたいときは Esc を押します。実行中の手順は終わり、あとの手順は始まりません。最後のメッセージに、pushしたブランチや保存したシークレットなど、すでに行われたことが一覧で出ます。GitHub Appを入れたあとに「Skip for now」を選べば、Appだけ入れた状態で止められ、あとで /install-github-app をもう一度実行すれば続きから進められます。すでに claude.yml があるリポジトリでは「Update workflow file with latest version」を選ぶと、新しい版のワークフローが新しいブランチに入ります。

認証のシークレットは、すでにClaude CodeにAPIキーがあればそれを使い、無ければ「サブスクリプションで長期トークンを作る」か「APIキーを貼る」かを選びます。ワークフローで /install-github-app のレビュー用ワークフローを選んだ場合、Claudeはレビューをプルリクエストにコメントとして投稿します（draftなど一部のプルリクエストは対象外です）。

この端末の手元の環境では、GitHubにログインした状態でしか進めない手順のため、/install-github-app の実行画面は掲載していません。上の画面は公式ドキュメントの表示です。

コピペで使える最小構成YAML（v1.0系）

PRやIssueで@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 }}

これは公式ドキュメントに載っている例と同じ内容です（2026年10月13日確認。手元のリポジトリでの実行確認はしていない）。押さえておく点は次のとおりです。

• contents: write：Claudeがファイルを書き換えてコミットするために必要です。read のままでは、質問への回答はできても変更を書き込めない
• id-token: write：アクションが既定で使うGitHub Appの認証に必要
• actions: read：プルリクエストのCIの結果をClaudeが読めるようにする
• if の行：@claude を含まないコメントでランナーが起動するのを防ぐ
• サブスクリプションで動かす場合は、anthropic_api_key の行を claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} に置き換える

設定できたら、IssueやPRのコメントに @claude この不具合を直してください のように書くと、Claudeが同じIssue・PRにコメントで返信し、作業の進み具合に合わせてそのコメントを更新します。

PRレビューを毎回自動実行し、ターン数や利用モデルを明示的に制御したい場合は、v1.0で追加されたclaude_argsに集約する形になります。

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "このPRの差分をレビューし、バグとセキュリティ上の懸念点を指摘してください"
          claude_args: |
            --max-turns 10
            --allowedTools Read,Grep,Glob

prompt を書いたワークフローは、メンションを待たずに動きます。この場合、結果は既定ではコメントではなくワークフローの実行ログに出ます。いずれも公式ドキュメントの構文に準拠した最小例であり、実際の運用ではpermissionsのスコープをタスクに必要な最小限に絞ることが前提になります。

PRが開かれたり更新されたりしたときに自動でレビューさせる例も、公式ドキュメントに載っています（プラグインの code-review を使う形。2026年10月13日確認。この記事では実行していません）。

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

--comment を付けるとレビューがプルリクエストへのコメントとして投稿されます（付けないと何も投稿されず、結果はワークフローの実行ログで読みます）。claude_args の行は、インラインコメントを投稿するためのMCPサーバーを起動させるために必要なので残します。公開リポジトリでは、フォークからのプルリクエストにはGitHubがシークレットを渡さないため、同じリポジトリ内のブランチからのプルリクエストだけが対象になります。ワークフローを自分で管理せずに自動レビューだけ使いたい場合は、前述の公式の Code Review 機能もあります。

v0.x → v1.0 破壊的変更 対応表

@betaタグの設定を流用したまま@v1に切り替えると、下表のパラメータ名の違いにより設定が無視されたりエラーになったりします。移行前に必ず確認したいです。

出典：anthropics/claude-code-action 公式移行ガイド

1年超の実運用で見えたGitHub連携特有の落とし穴

本記事監修者の河合継が3.5世代からClaude Codeを実務で運用してきた中で、GitHub連携まわりで実際に直面した課題は次の2点でした。数値やコスト試算のような検証できない情報ではなく、運用設計として再現可能な知見のみを共有します。

• CLAUDE.mdの肥大化リスク：リポジトリ直下のCLAUDE.mdに運用ルールを書き込んでいく設計は、Claude Codeが自動でGitHub操作を行う際の事故防止に有効だが、放置すると原則の数が際限なく増え続けます。当初20項目程度だったルールが実運用の中で40項目を超え、Claude自身が全文を読み切れず、後半に追記したルールが参照されにくくなる状態を経験しました。定期的に重複ルールを統合し、優先度の高いものを先頭に配置し直す、という保守作業が必要になります。
• 自動変更に対する切り戻し体制の必要性：Claude CodeがEdit/Writeツールでファイルを変更する直前に自動でバックアップを取るHook（PreToolUse Hook）を組み込むことで、GitHub連携経由の自動PR作成やIssue駆動の実装で意図しない変更が加わった場合でも、変更前の状態にすぐ切り戻せる体制を作りました。GitHub連携を「レビューなしで信頼する」のではなく、「いつでも巻き戻せる前提で使う」設計にしておくことが、失敗パターンを実害にしないための実務上のポイントになります。

実装の勘所：ブランチ戦略・権限設計・コスト管理の3要素

ブランチ戦略：AI専用ブランチの設計方針

Claude Codeによる自動コミットを本番ブランチに直接流すと、未レビューの変更が混入するリスクがあります。DevelopersIOの調査記事（2026/03/20、DevelopersIO）でも、コードベース規模に応じたコンテキスト管理の重要性が指摘されており、ブランチ設計とコンテキスト設計は表裏一体の問題として扱うべきです。推奨構成は以下のとおりです。

• claude/<issue-number> 命名規則でAI作業ブランチを自動生成し、人間のブランチと明確に区別する
• ブランチ保護ルールでmain・developへの直接pushをブロックし、PRを経由しないマージを禁止する
• PRレビューを人間が最終承認する「ヒューマン・イン・ザ・ループ」を必須化し、自動マージは段階的に導入する

前述の実践事例（Qiita・nakamasato）では、GitHub IssueでPlanを設計しArtifactとして固定してからClaude Codeに渡す手順が有効とされており、設計フェーズと実装フェーズを分離する構造がエージェントの暴走抑制に効果的とされています。

また、公式の Common Workflowsドキュメント では、並行セッションによる編集の衝突を避けるために git worktree を用いた並列セッション管理が推奨されています。複数のClaude Codeインスタンスを同時に走らせる場合には、この手法を採用することでマージコンフリクトのリスクを大幅に軽減できます。

権限設計：最小権限の原則を維持する

公式ドキュメントによれば、GitHub App経由でClaude Code GitHub Actionsをセットアップする場合、GitHub Actionsのアクションが使うのはContents・Issues・Pull requestsの読み書き権限です（AppをインストールするときにはActionsやChecksなどを含む権限一式が求められます。一覧は後述の表のとおりです）。GitHub Actions連携時にClaude Codeへ付与するトークンのスコープは、ユースケースに応じて厳密に絞り込みます。以下の表に一般的な権限マッピングを整理しました。

claude code github連携における権限スコープの推奨設定

ユースケース	必要なGitHubスコープ	推奨トークン種別	備考
コードレビューコメント生成のみ	pull-requests: write	GITHUB_TOKEN（Actions標準）	GitHub側の権限の例です。Claudeを動かす認証（APIキーかOAuthトークン）は別に必要です
ブランチ作成・コミット	contents: write	Fine-grained PAT	リポジトリ単位で制限し組織全体への権限付与を避ける
Issue読み取り・コメント	issues: write	Fine-grained PAT	読み取りのみならreadで十分
MCP経由フルエージェント動作	contents: write + pull-requests: write + issues: write	Fine-grained PAT（有効期限短縮）	定期ローテーションと監査ログの有効化を必須化

なお、公式アクションは github_token を渡さなければClaudeのGitHub Appとして認証するのが既定の動作で、自前のトークンは必須ではありません。標準の GITHUB_TOKEN を渡した場合、そのトークンで作られたコミットではGitHubが他のワークフローを起動しないため、ClaudeのコミットでCIが動かなくなる点に注意したい（公式ドキュメントのトラブルシューティング）。

Fine-grained PATはOrganization単位ではなくリポジトリ単位での発行を徹底することで、万一の漏洩時の影響範囲を限定できます。トークンの有効期限は最長でも90日以下を推奨し、GitHub Actions Secretsへの登録とローテーション手順をRunbookとして文書化しておきます。なお公式ドキュメントでは、コードはGitHubのランナー上にとどまる設計であることが「Secure by default」として明示されている（Claude Code GitHub Actions）。

組織で使うとき・やめるときの手順（公式）

クイックセットアップも手動セットアップも、1つのリポジトリごとの設定です。組織全体に広げる場合、公式ドキュメントは次の形を挙げています（2026年10月13日確認）。

• Claude GitHub Appを組織に1回だけ入れ、すべてのリポジトリか、選んだリポジトリに適用する
• 認証のシークレットは組織レベルのActionsシークレットに置く（リポジトリごとに持たない）。共有するシークレットには、claude setup-token で作ったOAuthトークンではなくClaude ConsoleのAPIキーを使うよう公式は勧めています（OAuthトークンは、そのトークンを作った人のサブスクリプションにひも付くため）
• ワークフローのファイルは、使いたいリポジトリごとに置くか、再利用できるワークフローとして1か所で定義して各リポジトリから呼び出す
• 長期のシークレットを持ちたくない場合は、GitHubのOIDCトークンとClaude Consoleのサービスアカウントを使うワークロードアイデンティティ連携も使えます（anthropic_federation_rule_id と anthropic_organization_id などの入力を指定し、ワークフローに id-token: write を付けます）

AppをインストールするときにGitHubが求める権限は、公式ドキュメントでは次の一式と説明されています。GitHub Appの権限は機能ごとには選べず、一式を受け入れる形になります（Code ReviewやWeb版のauto-fixなど、同じAppを使う別の機能の分も含まれます）。

権限	アクセス
Actions／Checks／Contents／Discussions／Issues／Pull requests／Repository hooks／Workflows	読み書き
Administration／Members／Merge queues／Metadata／Statuses	読み取り

これより狭い権限にしたい組織は、Contents・Issues・Pull requestsだけを持つ自前のGitHub Appを作る方法があると公式は説明しています（ただしこの場合、Code Reviewなどは公式のAppが必要です）。

やめるときは、(1) .github/workflows/ から anthropics/claude-code-action を使うワークフロー（クイックセットアップなら claude.yml と、選んだ場合は claude-code-review.yml）を削除、(2) ANTHROPIC_API_KEY または CLAUDE_CODE_OAUTH_TOKEN のシークレットを削除（シークレットを消しても元のキーは有効なままなので、完全に止めるにはConsoleでもキーを削除します）、(3) 他のClaudeの機能（Code Reviewなど）で使っていなければGitHub Appをアンインストール、の順で行います。

コスト管理：トークン消費の実態と上限設計

DevelopersIOの記事（2026/03/20）では、リポジトリ全体を読み込んだ状態での1タスク当たりのトークン消費量がコードベース規模に強く依存するとされており、大規模モノレポではコンテキストウィンドウの圧迫が精度低下とコスト増の両方を招くと指摘されています。対策として実績のある手法は以下のとおりです。

• CLAUDE.md を簡潔に保つ（実行のたびに読み込まれるため）。@claude への依頼は具体的に書き、Issueテンプレートで前提を先に渡す
• claude_args の --max-turns でやり取りの回数に上限を付ける
• タスクをIssue単位に細分化し、1回の呼び出しで渡すコンテキスト量を意図的に絞る
• GitHub ActionsのJobタイムアウトを設定し、エージェントの無限ループによるコスト超過を防ぐ
• 月次コスト上限をAnthropic管理コンソールで設定し、予算超過をアラートで検知する

なお、公式の Routinesドキュメント によれば、スケジュール実行・API呼び出し・GitHubイベント起動を組み合わせたルーティンをPro・Max・Team・Enterpriseプランで利用できます。たとえば「毎夜コネクタ経由でIssueを読み込み、ラベル付けとSlack通知を自動実行する」といった定常処理は、GitHub Actions上のワークフローに書くよりもルーティンとして管理する方がコスト設計も含めて整理しやすい場面がある（ただし研究プレビュー段階であり、仕様変更が生じうる点は留意が必要だ）。

費用の内訳について、公式ドキュメントは「1回の実行で2種類の資源を使う」と説明しています。1つはGitHub Actionsの実行時間（GitHub側の課金）、もう1つはClaudeのトークン（プロンプトと応答の長さ・タスクの複雑さ・コードベースの大きさで変わる）です。OAuthトークンで認証している場合は、API課金ではなくサブスクリプションの利用枠を使います。金額はタスクの粒度・コードベースの規模・モデルで大きく変わるため、少数のIssueで試して自チームの実測値を取ってから、上限（--max-turns・ジョブのタイムアウト・同時実行数の制限）を決めることを勧めます。

失敗パターンと技術的限界：過信を避けるための設計判断

実運用で頻出する失敗パターン4類型

Claude Codeのベストプラクティスをまとめたリポジトリ（GitHubスター3.6万超を記録、2026年4月時点でGitHubトレンド1位）が公開されており（出典：AI Heartland）、そこで言及される失敗パターンをエンジニア視点で再整理すると以下の4類型に集約されます。

1. 指示の曖昧さによる意図外実装
   「ユーザー認証を直せ」という粒度の指示では、認証ロジック全体を意図せずリファクタリングされるケースがあります。IssueにAcceptance Criteriaと変更対象ファイルの範囲を明文化することが前提条件です。公式の Common Workflowsドキュメント でも、編集に入る前にClaudeに計画を立てさせ、変更が実際にディスクに書き込まれる前にレビューする「Plan before editing」アプローチが明示的に推奨されています。
2. テストなし自動コミット
   テストランナーが未設定の環境ではClaude Codeはコミットまで実行するが、テスト通過を確認しません。後続のCIパイプラインによる検証を必ず配置し、テストが存在しないコードベースへの適用は段階的に行います。
3. 並行エージェントによるマージコンフリクトの誤解消
   複数のClaude Codeインスタンスが同一ファイルを並行編集した場合のコンフリクト解消で、誤った側の変更が採用されるリスクがあります。公式ドキュメントが推奨する git worktree を利用してセッションごとに独立したワーキングツリーを用意することで、このリスクを構造的に抑制できる（Common Workflows）。
4. 秘匿情報の意図しないコミット
   IssueやClaude Codeとの会話文脈にAPIキーや接続文字列が含まれると、コード中に展開されてコミットされるリスクがあります。git-secretsやgitleaks等のpre-commitフックとの併用を必須とし、シークレットスキャンをCI側でも二重に走らせます。

Claude Codeが技術的に苦手とする領域

Claude Codeは優れたコード生成能力を持つ一方、以下の領域では人間によるレビューを手厚くする必要があります。これらはツールの欠陥ではなく、現時点のLLMアーキテクチャが持つ構造的な限界であり、設計段階で織り込むべきトレードオフです。

• セキュリティ要件の高い認証・認可ロジック：CVSSスコアの高い脆弱性パターンを見落とすリスクがあり、セキュリティレビューの代替にはならない
• パフォーマンスクリティカルなボトルネック解消：プロファイリング結果の解釈や、マイクロベンチマーク基準での最適化判断は人間の介在が必要
• 文書化されていないレガシーコードの改修：コメントや設計書が不足している文脈では意図の読み取り精度が低下し、既存挙動の破壊につながりやすい
• インフラコード（Terraform等）の破壊的変更：terraform plan相当の差分確認を人間が実施しない限り、本番環境への意図しない影響が生じうる

設定したのに動かないときの確認ポイント

設定直後につまずきやすい点を、公式ドキュメントのトラブルシューティングから整理しました。

GitHub連携を実務で回してわかったこと（一次情報）

監修者・河合継はClaude Codeを3.5の時代から1年以上、実務で運用してきました。GitHubと組み合わせるときに実際に効いた勘所を補足します。

• 権限は「最小から」始めます。連携は便利な分、与える権限が広いほど想定外の操作リスクも増えます。最初は狭く始めて、必要に応じて広げるほうが、後の事故と稟議の手戻りが減りました。
• AIの変更も人のレビューを必ず通します。自動でPRやコミットまで進められても、マージ前の確認は人が握ります。生成された差分をそのまま通さず、採否を判断する工程を残すのが安全でした。
• 小さく区切ったIssue単位で任せると安定します。大きな要求を丸ごと投げるより、検証できる粒度のIssueに割って任せるほうが、結果の質も復旧のしやすさも高いです。

実践ワークフロー：Issue駆動開発への組み込みと段階的導入

推奨フロー設計：IssueをSingle Source of Truthとして扱う

現時点で実績のある構成は、GitHubのIssueを唯一の要件ソースとして扱い、Planと実装を明確に分離するフローです。Speakerdeck公開のClaude Code 2026年最新アップデート資料（2026/03/12、Speakerdeck）でも、IssueベースのワークフローがCI/CDとの親和性の観点から推奨されています。公式の Common Workflowsドキュメント も同様の手順を示しており、コードベース探索・バグ修正・リファクタリング・テスト・PR作成の各フェーズに対応した具体的なプロンプトレシピが公開されています。

1. Issue作成：エンジニアがAcceptance Criteria・変更対象ファイル範囲・技術制約を明文化します。曖昧な表現を排除する
2. @claudeメンションまたはラベル付与でActions起動：PRやIssueへの @claude メンションがトリガーです。手動介入をゼロにするのではなく、起動判断は人間が担う
3. Claude Codeによる自律実装：claude/issue-xxxブランチを自動作成し、コミットしてDraft PRをオープン
4. CIによる自動検証：テスト・Lint・シークレットスキャンをパスしたらPRをReady for Reviewに昇格
5. 人間によるレビューとマージ：差分をレビューし承認またはRevisionを要求します。最終マージは人間が担う

使い方全体の体系的な把握には使い方ガイド、導入直後の試行段階でははじめの一歩ガイドが参考になります。

GitHub Enterprise Server利用時の注意点

公式ドキュメントによれば、GitHub Enterprise Server（GHES）はTeamおよびEnterpriseプランで利用できます。GHES対応範囲は以下のとおりです。

• Claude Code on the web・Code Review・Claude Security・Teleportセッション・プラグインマーケットプレイス・コントリビューションメトリクス・GitHub Actionsはいずれもサポート済み
• GitHub Actionsについては手動でのワークフロー設定が必要であり、/install-github-app コマンドはgithub.com専用であるため使用不可
• GitHub MCPサーバーは現時点で非対応
• プラグインマーケットプレイスでは owner/repo の短縮表記ではなく完全なgit URLを使用する必要がある

他のAIコーディングツールとの棲み分け

claude code githubの連携を検討する際、IDE補完型ツールとの使い分けは重要な設計判断です。Claude Codeはリポジトリ全体のコンテキストを持つエージェント型であるため、単一ファイルの補完や小規模な編集補助を主目的とするユースケースでは過剰な選択になる場合もあります。ツールの選択基準についてはClaude Code vs Cursor比較記事およびClaude Code vs Codex比較記事で詳細に論じています。

研究・教育分野における検証事例

J-STAGE掲載論文「ソフトウェア開発PBLへのAIエージェントを活用した仕様駆動開発」（J-STAGE）は、ソフトウェア開発の演習授業にAIエージェントを使った仕様駆動開発（調査・計画・実装・レビューの4工程）を取り入れた報告です。開発の効率が上がった一方で、受講者の理解が追いつかない傾向も報告されており、チームに導入するときの教育の設計を考える材料になります。

よくある質問

Q. Claude CodeとGitHubを連携させる方法にはどのような種類がありますか？
A. 権限モデル・自動化範囲・運用コストの観点から3つのレイヤーに整理できます。レイヤー1はローカルCLI×Gitコマンド直接実行、レイヤー2はGitHub Actionsへの組み込み（Claude Code Action）、レイヤー3はMCP（Model Context Protocol）経由のGitHub統合です。

Q. GitHub Actionsの公式アクションを使うと何ができますか？
A. PRやIssueで@claudeとメンションするだけで、コードの分析・PR作成・機能実装・バグ修正を自動実行できます。Anthropicが公式に提供するclaude-code-actionリポジトリを使うことで、YAML記述量を最小化した組み込みが可能です。

Q. /install-github-appコマンドでは何が行われますか？
A. ターミナルでClaude Codeを起動してこのコマンドを実行すると、GitHub Appのインストール、認証用のシークレットの登録、ワークフローファイルを入れたプルリクエストの準備までを案内してくれます。リポジトリの管理者権限と、GitHub CLI（gh）のログインが必要です。使えるのはgithub.comのリポジトリだけで、Claude APIのキーとClaudeのサブスクリプションのどちらでも設定できます。Amazon Bedrock・Google CloudのAgent Platform・Microsoft Foundry経由で使う場合は、クラウド事業者向けの手順で設定します。

Q. GitHub MCPサーバーはGitHub Enterprise Serverで使えますか？
A. 公式ドキュメントによれば、GitHub MCPサーバーはGitHub Enterprise Server（GHES）では現時点で非対応です。GHES環境での利用を検討する場合はこの制約を事前に確認しておく必要があります。

Q. v0.x系からv1.0のclaude-code-actionへ移行する際、何が変わりますか？
A. mode・direct_prompt・override_prompt・max_turns・model・allowed_tools／disallowed_tools・mcp_config・timeout_minutesといったパラメータの指定方法が変わります。多くはclaude_argsへのCLI引数形式への統合や、GitHub Actions側のtimeout-minutesへの移動が必要になります。

Q. 実運用で頻出する失敗パターンにはどのようなものがありますか？
A. 「指示の曖昧さによる意図外実装」「テストなし自動コミット」「並行エージェントによるマージコンフリクトの誤解消」「秘匿情報の意図しないコミット」の4類型に集約されます。

Q. 複数のClaude Codeインスタンスを並行して走らせる場合、何を使うとよいですか？
A. 公式のCommon Workflowsドキュメントで推奨されているgit worktreeを用いて、セッションごとに独立したワーキングツリーを用意することで、マージコンフリクトのリスクを構造的に抑制できます。

Q. GitHub連携においてClaude Codeが技術的に苦手とする領域は何ですか？
A. セキュリティ要件の高い認証・認可ロジック、パフォーマンスクリティカルなボトルネック解消、文書化されていないレガシーコードの改修、インフラコード（Terraform等）の破壊的変更の4つの領域では、人間によるレビューを手厚くする必要があります。

Q. Claude Codeを使わずに、ClaudeのチャットからGitHubのリポジトリを読ませることはできますか？
A. できます。公式ヘルプによると、チャットの入力欄の「+」から「Add from GitHub」を選ぶか、プロジェクトの知識に「GitHub」からリポジトリを追加すると、選んだファイルやフォルダをClaudeに読ませられます。読み込まれるのは指定したブランチのファイル名と中身だけで、コミット履歴やプルリクエストは対象外です。コードの変更やプルリクエストの作成まで任せたい場合はClaude Codeを使います。

Q. Claudeのサブスクリプション（Pro・Maxなど）だけでGitHub Actionsを動かせますか？
A. 動かせます。公式ドキュメントによると、手元で claude setup-token を実行して作ったトークンを CLAUDE_CODE_OAUTH_TOKEN という名前でリポジトリのシークレットに登録し、ワークフローの claude_code_oauth_token に渡します。Pro・Max・Team・Enterpriseで使え、この場合の実行はAPIの従量課金ではなくサブスクリプションの利用枠を使います。複数のリポジトリで共有する場合は、個人のサブスクリプションにひも付かないAPIキーが勧められています。

Q. @claudeとメンションしても反応しないときは何を確認すればよいですか？
A. 公式ドキュメントは次の5点を挙げています。GitHub Appがそのリポジトリにインストールされているか、リポジトリでワークフローが有効か、APIキーまたはOAuthトークンがシークレットに登録されているか、コメントに「@claude」が単語として入っているか（/claude や @claude-bot では反応しません）、コメントした人がリポジトリの書き込み権限を持っているか、です。

Q. リポジトリを見られる人なら誰でも@claudeで起動できますか？
A. できません。公式ドキュメントによると、IssueやPRのイベントでは、起動した人がリポジトリの書き込み権限を持っている必要があります。また、ボットによる起動は、許可リスト（allowed_bots）に入れない限り拒否されます。ボット同士でClaudeを呼び続けるループを防ぐための仕組みです。

---

まとめ

Claude CodeとGitHubの連携は、ローカルCLI・GitHub Actions・MCPの3つのレイヤーに整理することで、チームのリスク許容度と自動化ニーズに合った設計選択が可能になります。公式ドキュメントが示すとおり、@claude メンションによるActions起動・/install-github-app による簡易セットアップ・CLAUDE.md によるプロジェクト標準の継承といった仕組みが整備されており、導入障壁は着実に下がっています。一方で、権限スコープの最小化・ブランチ保護ルールの徹底・「Plan before editing」アプローチによる意図外実装の抑制は、いずれのレイヤーでも共通して必要な設計判断です。セキュリティ要件の高い領域や文書化が不十分なレガシーコードへの適用は段階的に行い、常に人間によるレビューを最終工程として組み込むことが、持続可能なAI活用の前提条件となります。

参考文献

• Anthropic公式「Claude Code GitHub Actions」https://code.claude.com/docs/en/github-actions.md
• Anthropic公式「Common Workflows」https://code.claude.com/docs/en/common-workflows.md
• Anthropic公式「Claude Code with GitHub Enterprise Server」https://code.claude.com/docs/en/github-enterprise-server.md
• Anthropic公式「Automate work with routines」https://code.claude.com/docs/en/routines.md
• Anthropic公式「Claude Agent SDK」https://code.claude.com/docs/en/agent-sdk/overview
• claude-code-action（GitHubリポジトリ）https://github.com/anthropics/claude-code-action
• Gigazine「Claude CodeはGitHubの公開コミットの4％を占めており2026年末には20%へ」（2026/02/10）https://gigazine.net/news/20260210-claude-code-github-commits-4-percent-20-percent/
• Ledge.ai「GitHubコミットの4％がAI生成──Claude Codeは2026年末に20％へ？SemiAnalysisが分析」https://ledge.ai/articles/claude_code_4_to_20_percent_github_growth
• Classmethod DevelopersIO「[2026年版] Claude Code を知ります。」（2026/03/20）https://dev.classmethod.jp/articles/shoma-2026-claude-code-know-use-leverage/
• Qiita・nakamasato「[Claude Code] AIコーディング開発サイクル (2026年1月時点)」（2026/01/18）https://qiita.com/nakamasato/items/ef3842b05b5b936906f6
• AI Heartland「Claude Codeベストプラクティス2026｜Boris直伝の25 Tips」（2026/04/11）https://ai-heartland.com/explain/claude-code-best-practice-guide-2026/
• Uravation Media「【2026年最新】Claude Code GitHub連携完全ガイド」（2026年6月取得）https://uravation.com/media/claude-code-github-integration-guide-2026/
• Speakerdeck・oikon48「Claude Code 2026年 最新アップデート」（2026/03/12）https://speakerdeck.com/oikon48/claude-code-0312
• J-STAGE「ソフトウェア開発PBLへのAIエージェントを活用した仕様駆動開発」https://www.jstage.jst.go.jp/article/repit/2026/0/2026_90/_pdf

関連記事

• Claude Codeとは
• Claude Codeで自動化・定期実行する方法
• Claude Codeのベストプラクティス
• Claude Code Skillsとは？作り方と一覧
• Claude Codeでできること・活用事例