--- title: "GitLabでPR-AgentのAIコードレビューを導入する手順｜CI・Webhook・Qodo Merge Proの選び方" url: "https://www.issoh.co.jp/tech/details/2575/" published: 2024-06-14 updated: 2026-07-19 categories: ["GitHub"] publisher: "株式会社一創" --- # GitLabでPR-AgentのAIコードレビューを導入する手順｜CI・Webhook・Qodo Merge Proの選び方 PR-Agentは、マージリクエスト（MR）に対して要約・レビュー・改善提案を自動で書き込むオープンソースのAIコードレビューツールです（開発元はQodo、リポジトリは`qodo-ai/pr-agent`）。GitHubだけでなくGitLabにも対応していますが、GitLab連携には「CI/CDパイプライン」「自前のWebhookサーバー」「ホスト版のQodo Merge Pro」という性格の異なる3つの入り口があり、どれを選ぶかで運用の手間が大きく変わります。この記事では、それぞれの設定手順を実際の設定コード付きで示し、必要な環境変数と、導入時につまずきやすい箇所の対策までを整理します。 ## まとめ：GitLab連携は3方式、まず試すならCI/CDパイプライン - **最短で試す**：GitLabの`.gitlab-ci.yml`にPR-Agentのジョブを1つ追加する方式。常駐サーバー不要で、対象は設定したプロジェクトのみ。 - **複数リポジトリで常時運用**：`gitlab_webhook`ターゲットのDockerイメージを立てるWebhookサーバー方式。サーバー1台で複数プロジェクトを横断的にカバーできる。 - **サーバーを持ちたくない**：Qodoが提供するホスト版[Qodo Merge](https://www.issoh.co.jp/tech/details/6871/)（Pro）。Webhookを登録するだけで運用でき、サーバー保守が不要。 - **共通で必要なもの**：`api`スコープを持つGitLabパーソナルアクセストークンと、OpenAIなどLLMのAPIキー。トークン類はコードに直書きせず、CI/CD変数か環境変数で渡す。 - OSS本体は無料。かかるのは各LLMの利用料で、Qodo Merge Proは別途サブスクリプション。PR-Agent全般の料金や機能は[PR-Agentとは](https://www.issoh.co.jp/tech/details/7152/)で解説しています。 ## PR-AgentとGitLabを連携する3方式の違い ### PR-Agent（Qodo Merge）のGitLab対応の位置づけ PR-Agentは、MRの差分を読み取り、`/describe`（説明生成）・`/review`（レビュー）・`/improve`（改善提案）といったコマンドの結果をMRのコメントとして投稿します。`/ask`（コードへの質問）や`/update_changelog`（変更履歴生成）などもあり、MRのコメント欄からその場で呼び出せます。GitLabでは、これらをMR作成時に自動実行させるか、コメントで手動実行させるかを選べます。なお、PR-Agentのオープンソース版はQodo Merge（旧CodiumAI PR-Agent）として開発が続いており、両者の位置づけの違いは[Qodo Merge とは](https://www.issoh.co.jp/tech/details/6871/)で整理しています。 ### CI/CD・Webhook・Proの選択基準 | 方式 | 常駐サーバー | 適用範囲 | 向いている場面 | | -------------- | -------- | ------------ | ------------- | | CI/CDパイプライン | 不要 | 設定したプロジェクト単位 | まず1リポジトリで試す | | Webhookサーバー | 必要 | 複数プロジェクト横断 | 多数のリポジトリで常時運用 | | Qodo Merge Pro | 不要（SaaS） | 契約範囲 | サーバー保守を避けたい | 判断の軸はシンプルで、**対象が1〜数リポジトリで試験導入ならCI/CDパイプライン**、**組織全体で常時レビューを効かせたいならWebhookサーバーかQodo Merge Pro**です。自前のインフラ運用リソースが薄いチームが、いきなりWebhookサーバーを常時稼働させるのは保守負担が見合わないことが多く、その場合はホスト版のProが現実的です。 ## CI/CDパイプラインで最短導入する手順 ### .gitlab-ci.yml にPR-Agentのジョブを追加する 常駐サーバーを立てずに始めるなら、リポジトリの`.gitlab-ci.yml`にMRイベントで走るジョブを追加します。MR作成・更新時に`describe`・`review`・`improve`を順に実行する最小構成は次のとおりです。 ``` stages: - pr_agent pr_agent_job: stage: pr_agent image: name: pragent/pr-agent:latest entrypoint: [""] script: - cd /app - export MR_URL="$CI_MERGE_REQUEST_PROJECT_URL/merge_requests/$CI_MERGE_REQUEST_IID" - export gitlab__url=$CI_SERVER_PROTOCOL://$CI_SERVER_FQDN - export gitlab__PERSONAL_ACCESS_TOKEN=$GITLAB_PERSONAL_ACCESS_TOKEN - export config__git_provider="gitlab" - export openai__key=$OPENAI_KEY - python -m pr_agent.cli --pr_url="$MR_URL" describe - python -m pr_agent.cli --pr_url="$MR_URL" review - python -m pr_agent.cli --pr_url="$MR_URL" improve rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' ``` ジョブは`merge_request_event`のときだけ動くよう`rules`で絞っています。Dockerイメージは、リリース0.34.2以降で配布される現行の`pragent/pr-agent:latest`を指定しています。旧`codiumai/pr-agent`名前空間はv0.31で凍結され新しいイメージが追加されないため、既定には使いません。イメージ名は今後も変わりうるので、導入前に公式ドキュメントで最新のタグを確認してください。 ### CI/CD変数にトークンとAPIキーを登録する 上のYAMLは`$GITLAB_PERSONAL_ACCESS_TOKEN`と`$OPENAI_KEY`を参照します。これらはコードに書かず、GitLabプロジェクトの「設定 > CI/CD > 変数（Variables）」でMasked変数として登録します。パーソナルアクセストークンは、対象プロジェクト/グループにアクセスできるユーザーで発行し、`api`スコープを付与します。トークンの権限が狭いとMRへのコメント投稿に失敗するため、レビューを書き込む前提のスコープ設定が必要です。 ### 自動実行される3コマンドの役割 MRが作られると、`describe`がタイトルと概要を、`review`が指摘とリスク評価を、`improve`が具体的なコード改善案を投稿します。この3つはレビュー着手前の一次情報として機能し、レビュアーは「AIが拾った論点を人が判断する」流れに集約できます。全コマンドの一覧や設定は[PR-Agentの使い方](https://www.issoh.co.jp/tech/details/7152/)で確認できます。 ## Webhookサーバー方式で複数プロジェクトに常時適用する手順 ### Dockerイメージのビルドと環境変数 複数リポジトリを1つのサーバーで面倒みるなら、`gitlab_webhook`ターゲットでイメージをビルドしてWebhookサーバーを常駐させます。まず、Webhook検証用の共有シークレットを生成します。 ``` SHARED_SECRET=$(python -c "import secrets; print(secrets.token_hex(10))") ``` 次に、リポジトリをクローンしてWebhookサーバー用イメージをビルドします。 ``` docker build . -t gitlab_pr_agent --target gitlab_webhook -f docker/Dockerfile ``` コンテナ起動時には、プロバイダ・トークン・シークレット・LLMキーを環境変数で渡します。GitLabをセルフマネージド運用している場合は`GITLAB__URL`を自社のURLに変更します。 ``` export CONFIG__GIT_PROVIDER=gitlab export GITLAB__PERSONAL_ACCESS_TOKEN= export GITLAB__SHARED_SECRET= export GITLAB__URL=https://gitlab.com export OPENAI__KEY= export PORT=3000 ``` ### GitLab Webhookの登録（URL・シークレット・トリガー） サーバーを起動したら、GitLabのプロジェクト設定でWebhookを登録します。URLはサーバーのホスト名に`/webhook`を付けた`https:///webhook`、シークレットトークンには先ほど生成した共有シークレットを設定します。トリガーは「プッシュイベント」「コメント」「マージリクエストイベント」を有効にします。シークレットが一致しないとリクエストが弾かれ、レビューが一切動かないため、GitLab側とサーバー側の値が同一であることを必ず確認してください。 ### .pr\_agent.toml でレビュー挙動を調整する レビューの言語やコマンドの挙動は、リポジトリのルートに置く`.pr_agent.toml`で上書きできます。たとえば日本語でレビューさせ、MRのタイトルを自動生成させる設定は次のようになります。 ``` [pr_reviewer] extra_instructions = "レビューコメントは日本語で記述してください。" [pr_description] generate_ai_title = true ``` `extra_instructions`にプロジェクト固有のコーディング規約を書いておくと、その観点をレビューに反映させられます。リポジトリごとに`.pr_agent.toml`を置けるため、Webhookサーバーを共有しつつプロジェクト単位でレビュー方針を変えられるのがこの方式の利点です。 ## Qodo Merge Pro（ホスト版）でサーバー運用を省く選択肢 Webhookサーバーの構築・保守を避けたい場合は、Qodoがホストするマネージド版を使い、Webhookを登録するだけで運用できます。GitLabでは、WebhookのURLにQodoが指定するエンドポイント（`https://pro.gitlab.pr-agent.codium.ai/webhook`）、シークレットトークンに自分のQodoキーを設定し、「コメント」「マージリクエストイベント」を有効化します。自前サーバーのビルドやアップデート追随が不要になる一方、コードをサードパーティのサービスに渡すことになるため、社外にコードを出せない環境では前述のセルフホスト（CI/CDまたはWebhookサーバー）を選びます。ホスト版とOSS版の機能差は[Qodo MergeとPR-Agentの違い](https://www.issoh.co.jp/tech/details/6871/)で整理しています。 ## 導入時につまずくポイントと対策 GitLab連携で止まりやすいのは、コードそのものより権限・シークレット・トリガーの設定です。実際にレビューが動かないときは、次の順で確認すると原因を切り分けやすくなります。 - **トークンのスコープと権限**：パーソナルアクセストークンに`api`スコープが無い、あるいは発行ユーザーがMRにコメントできる権限を持たないと、レビュー結果を投稿できません。読み取りだけでなく書き込みが要る点に注意します。 - **シークレットの不一致**：Webhook方式でGitLab側のシークレットトークンとサーバーの`GITLAB__SHARED_SECRET`がずれていると、リクエストが認証で弾かれます。両者をコピー&ペーストで揃えます。 - **トリガーイベントの選択漏れ**：Webhookで「マージリクエストイベント」にチェックが無いと、MRを作っても何も起きません。手動コマンドを使うなら「コメント」も有効にします。 - **セルフマネージドGitLabのURL**：GitLab.com以外を使う場合、`GITLAB__URL`（CIでは`gitlab__url`）を自社ホストに向けないと、APIの向き先が食い違います。 - **LLMのコスト**：レビュー実行ごとにLLMのトークンを消費します。大きなMRや高頻度の自動実行はコストに直結するため、対象ブランチやMRサイズで実行条件を絞る設計が有効です。 「まず全社で常時レビューを効かせたい」という理由だけで最初からWebhookサーバーを常駐させるのは、運用担当が薄いチームには過剰です。1リポジトリのCI/CDパイプラインで効果と精度を検証し、価値が確認できてからWebhookサーバーやQodo Merge Proへ広げる段階導入のほうが、無駄なインフラ保守を避けられます。 ## よくある質問 ### PR-AgentはGitLabのセルフマネージド版でも使えますか？ 使えます。CI/CDパイプライン方式なら`gitlab__url`に`$CI_SERVER_PROTOCOL://$CI_SERVER_FQDN`を、Webhookサーバー方式なら`GITLAB__URL`に自社のGitLab URLを設定して、APIの向き先を自社ホストに合わせます。 ### PR-Agentの利用に料金はかかりますか？ オープンソース本体は無料ですが、レビューにはOpenAIなどLLMのAPI利用料が実行ごとに発生します。ホスト版のQodo Merge Proは別途サブスクリプション費用がかかります。料金体系の詳細は[PR-Agentの導入・料金](https://www.issoh.co.jp/tech/details/7152/)を参照してください。 ### GitHubで使う場合と設定は違いますか？ 基本のコマンド（`/review`など）は共通ですが、認証やWebhookの登録手順、環境変数の指定はプラットフォームごとに異なります。GitHub側の手順は[PR-Agentとは（GitHub版の使い方）](https://www.issoh.co.jp/tech/details/7152/)にまとめています。 ### Qodo MergeとPR-Agentは何が違いますか？ PR-Agentはオープンソース版の呼称で、Qodo Merge（Pro）はQodoが提供するホスト版・上位機能を含むサービスです。機能差と選び分けは[Qodo Merge とは](https://www.issoh.co.jp/tech/details/6871/)で解説しています。 ### OpenAI以外のLLMは使えますか？ 使えます。PR-Agentはモデルを設定で切り替えられ、OpenAIのほかGoogle Geminiやその他のプロバイダを指定できます。利用するプロバイダに応じてAPIキーの環境変数（例：`OPENAI__KEY`）を差し替えます。変動が速い領域のため、対応モデルの最新状況は公式ドキュメントで確認してください。 ## 関連記事 - [PR-Agent（PRエージェント）とは｜GitHubのPRレビューをAIで自動化する使い方・導入・料金](https://www.issoh.co.jp/tech/details/7152/) - [Qodo Merge とは｜GitHubのPRレビューをAIで自動化する使い方・料金・PR-Agentとの違い](https://www.issoh.co.jp/tech/details/6871/) - [GitHubとGitLabの違いを比較｜CI/CD・セキュリティで選ぶ判断基準](https://www.issoh.co.jp/tech/details/4219/) --- 出典: [GitLabでPR-AgentのAIコードレビューを導入する手順｜CI・Webhook・Qodo Merge Proの選び方]()（株式会社一創）