GitHub ActionsのComposite ActionによるAIコードレビュー基盤

こんにちは、REALITY株式会社エンジニアリング部のうすぎぬです。

REALITYでは、開発速度の向上と品質担保の両立を目指し、AI技術の活用を積極的に進めています。近年、Claude CodeのようなAIコーディングエージェントの登場により、個々の開発者の実装速度は飛躍的に向上しました。しかしその一方で、PRの増加に伴うレビュー負荷の高まりという新たな課題も生まれています。

この課題を解決するため、私たちはClaudeなどのLLMを活用したAIによるレビュー補助の仕組みを導入しました。本記事では、そのレビューワークフローを技術領域横断でスケールさせるために構築した、「GitHub ActionsのComposite ActionによるAIコードレビュー基盤」の活用事例をご紹介します。

背景：AIレビュー導入と見えてきた課題

AIによるレビュー補助の取り組みとして、私たちは anthropics/claude-code-action を利用し始めました。PRに対してAIが自動でレビューコメントを付けてくれるこの仕組みは、レビュワーの負担軽減やレビュー品質の標準化に大きな効果をもたらしました。

しかし、この仕組みを複数のリポジトリに展開していく中で、いくつかの運用上の課題が見えてきました。

課題1：リポジトリごとに設定が乱立し、管理が煩雑になった

claude-code-action は非常に強力ですが、利用するにはいくつかの設定が必要です。特に私たちは、セキュリティガバナンスやコスト管理の観点から、LLMの利用をGoogle CloudのVertex AI経由に統一しています。そのため、各リポジトリのワークフローファイルに、以下のような認証情報やモデル設定を個別に記述する必要がありました。

• GCPのWorkload Identity連携設定
• 利用するLLMのモデルID
• AIに与える指示

これらの設定は全リポジトリで統一すべきものですが、リポジトリごとにコピー＆ペーストで管理していると、些細な変更でもすべてのリポジトリを修正して回る必要があり、非常に手間がかかります。

課題2：LLMのアップデートへの追従が煩雑になった

LLMは日々進化しており、より高性能なモデルが次々とリリースされます。例えば、新しいモデル（claude-opus-4-1@20250805 など）がリリースされた際に、全プロジェクトでその恩恵を受けるためには、すべてのリポジトリの設定ファイルを手動で更新する必要がありました。REALITYには多数のプロジェクトリポジトリが存在するため、このアップデート対応は非常に煩雑な作業になっていました。

これらの課題を解決し、全リポジトリで統一されたAIレビュー基盤を効率的に運用するため、私たちはGitHub ActionsのComposite Actionに着目しました。

Composite Actionによる設定の一元管理

Composite Actionは、複数のワークフローステップを1つのアクションとしてまとめ、再利用可能にするGitHub Actionsの機能です。

私たちは、この仕組みを利用して、AIレビューに関する共通設定をすべて詰め込んだアクションを作成し、Organization内の共有リポジトリ（reality-actions）で一元管理することにしました。

システム構成

現在のアーキテクチャは以下のようになっています。

各プロジェクトリポジトリ（例では reality-servers, reality-unity, reality-tools など）のワークフローは、reality-actions リポジトリにあるComposite Actionを uses 句で呼び出すだけです。実際のGCP認証やClaudeへの指示（プロンプト）、モデルバージョンの指定などは、すべて reality-actions 側で完結しています。

この構成により、各リポジトリはLLMに関する複雑な設定を意識する必要がなくなります。また、モデルのバージョンを更新したい場合は、reality-actions リポジトリを1つ修正するだけで、それを参照しているすべてのリポジトリに一括で反映されるようになりました。

利用例：シンプルになったワークフロー定義

Composite Actionの導入後、各プロジェクトのワークフローファイルは次のように非常にシンプルになりました。

# 各プロジェクトリポジトリの .github/workflows/claude-review.yml
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      id-token: write
      contents: read
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Claude Review
        uses: your-organization/reality-actions/claude-review@main
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          service_account: ${{ vars.GCP_CLAUDE_SERVICE_ACCOUNT }}
          workload_identity_provider: ${{ vars.GCP_CLAUDE_WORKLOAD_IDENTITY_PROVIDER }}

uses: your-organization/reality-actions/claude-review@main の一行で、後述する認証やプロンプト設定を含んだレビューアクションを呼び出しています。

実装の紹介：claude-review/action.yaml

こちらが、共通基盤リポジトリ reality-actions で管理しているComposite Actionの実装（改変あり）です。
（このpromptは、Claude Code ActionでPRにインラインコメント（Inline Comment）を投稿する際の参考例としてもご利用いただけます。）

claude-review/action.yaml:

name: "Claude Code Review"
description: "Setup Google Cloud authentication and Claude code action"

# 利用側から受け取る引数（inputs）
inputs:
  github_token:
    description: "GitHub token for Claude action"
    required: true
  service_account:
    description: "GCP service account"
    required: true
  workload_identity_provider:
    description: "GCP workload identity provider"
    required: true
  trigger_phrase:
    description: "Trigger phrase for Claude"
    required: false
    default: "@claude"
  timeout_minutes:
    description: "Timeout in minutes"
    required: false
    default: "60"
  allowed_tools:
    description: "Allowed tools for Claude"
    required: false
    default: "mcp__github__create_pending_pull_request_review,mcp__github__get_pull_request_diff,mcp__github__add_comment_to_pending_review,mcp__github__submit_pending_pull_request_review"
  # モデル名やプロンプトはデフォルト値をここで一元管理
  model:
    description: "Claude model to use"
    required: false
    default: "claude-opus-4-1@20250805"
  direct_prompt:
    description: "Direct prompt for Claude"
    required: false
    default: |
      このプルリクエスト（PR）をレビューし、GitHub のレビュー機能を使ってフィードバックをしてください。作業は次の手順に沿って進めてください：
      1.  **CLAUDE.mdの内容を確認する:** CLAUDE.mdの内容を確認し、コーディングガイドラインやレビューの方針を理解してください。
      2.  **レビューを開始する:** `mcp__github__create_pending_pull_request_review` を使って、保留中のレビューを開始します。
      3.  **変更内容を確認する:** `mcp__github__get_pull_request_diff` を使って、コードの変更点や行番号を把握します。
      4.  **インラインコメントを追加する:** 改善点や懸念事項があるコードの行には `mcp__github__add_comment_to_pending_review` を使ってコメントを追加してください。修正方針が明確な場合には積極的にsuggestionを利用してください。
      5.  **レビューを提出する:** `mcp__github__submit_pending_pull_request_review` を使って、イベントタイプを「COMMENT」に設定し、全体のまとめコメントと共にレビューを提出してください（※「REQUEST_CHANGES」は使わないでください）。

      **コメントの書き方に関する重要事項**

      * **インラインコメントの構成:**
          * **結論を先に:** 各インラインコメントの冒頭で、指摘内容の要点を一行で簡潔に述べてください。
          * **理由と提案:** 結論の後に、そのように判断した理由や背景、具体的な修正案を詳しく説明してください。
          * **指摘中心に:** インラインコメントは、修正提案、バグの可能性、可読性の問題など、具体的な改善点に焦点を当ててください。

      * **ポジティブなフィードバックについて:**
          * **インラインでは控えめに:** インラインで言及するのは、特に優れた設計や他の開発者の参考になるような独創的な実装など、特筆すべき点に限定します。
          * **まとめコメントで言及:** 全体的に良かった点や、PR全体に対するポジティブな感想は、レビュー提出時の「まとめコメント」に集約して記述してください。
      (以下、長文のため省略)

# 実行するステップ（runs）
runs:
  using: "composite"
  steps:
    # 1. GCP認証
    - name: Authenticate to Google Cloud
      id: auth
      uses: google-github-actions/auth@v2
      with:
        service_account: ${{ inputs.service_account }}
        workload_identity_provider: ${{ inputs.workload_identity_provider }}

    # 2. Claude Code Actionの実行
    - name: Setup Claude Code Action
      uses: anthropics/claude-code-action@beta
      with:
        use_vertex: "true"
        github_token: ${{ inputs.github_token }}
        trigger_phrase: ${{ inputs.trigger_phrase }}
        timeout_minutes: ${{ inputs.timeout_minutes }}
        allowed_tools: ${{ inputs.allowed_tools }}
        model: ${{ inputs.model }}
        direct_prompt: ${{ inputs.direct_prompt }}
      env:
        ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
        CLOUD_ML_REGION: us-east5

このアクションのポイントは以下の通りです。

1. 設定の抽象化:
   runs.steps の中で google-github-actions/auth によるGCP認証と anthropics/claude-code-action の呼び出しという2つのステップをまとめています。利用側はこれらの詳細を知る必要がありません。
2. デフォルト値による一元管理:
   inputs セクションで model や direct_prompt といった重要な設定に default 値を設定しています。これにより、ほとんどのリポジトリは with 句でこれらの値を指定する必要がなく、自動的に全技術領域標準の設定が適用されます。プロンプトを改善したい場合も、この default 値を修正するだけで全リポジトリに展開できます。
3. 柔軟性の確保:
   inputs として定義しているため、特定のリポジトリでだけモデルやプロンプトを一時的に変更したい、といった特殊なケースにも柔軟に対応できます。

この仕組みによって、私たちはLLMのモデル更新やプロンプトチューニングといった改善活動を、リポジトリの数に臆することなく迅速に行えるようになりました。

まとめ

本記事では、GitHub ActionsのComposite Actionを活用して、全技術領域横断で利用可能なAIコードレビュー基盤を構築した事例を紹介しました。

この取り組みによって得られたメリットは以下の通りです。

• 設定の抽象化と簡素化: 各リポジトリのワークフロー定義が非常にシンプルになり、導入のハードルが下がりました。
• メンテナンス性の大幅な向上: モデルのバージョンやプロンプトの更新が、共通リポジトリの一箇所の修正で完了するようになりました。
• ガバナンスの強化: Vertex AIへの認証や利用モデルを共通基盤で統制でき、セキュリティとコスト管理が強化されました。
• 開発体験の標準化: 全リポジトリで統一された品質のAIレビューを提供できるようになり、開発者体験の向上に繋がりました。

AIの活用が当たり前になる中で、その設定や運用をいかに効率化・標準化していくかは、組織全体の開発力を向上させる上で重要な鍵となります。Composite Actionは、そのための非常に強力なツールの一つです。

REALITYでは、今後もAIをはじめとする新しい技術を積極的に活用し、より良い開発プロセスを追求していきます。この記事が、皆さんの開発ワークフロー改善のヒントになれば幸いです。