公開2024.06.14更新2026.07.19 GitHub

GitLabでPR-AgentのAIコードレビューを導入する手順｜CI・Webhook・Qodo Merge Proの選び方

Q: PR-AgentはGitLabのセルフマネージド版でも使えますか？

使えます。CI/CDパイプライン方式なら gitlab__url に $CI_SERVER_PROTOCOL://$CI_SERVER_FQDN を、Webhookサーバー方式なら GITLAB__URL に自社のGitLab URLを設定して、APIの向き先を自社ホストに合わせます。

Q: GitHubで使う場合と設定は違いますか？

基本のコマンド（ /review など）は共通ですが、認証やWebhookの登録手順、環境変数の指定はプラットフォームごとに異なります。GitHub側の手順は PR-Agentとは（GitHub版の使い方） にまとめています。

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（Pro）。Webhookを登録するだけで運用でき、サーバー保守が不要。
共通で必要なもの：apiスコープを持つGitLabパーソナルアクセストークンと、OpenAIなどLLMのAPIキー。トークン類はコードに直書きせず、CI/CD変数か環境変数で渡す。
OSS本体は無料。かかるのは各LLMの利用料で、Qodo Merge Proは別途サブスクリプション。PR-Agent全般の料金や機能はPR-Agentとはで解説しています。

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 とはで整理しています。

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の使い方で確認できます。

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=<personal_access_token>
export GITLAB__SHARED_SECRET=<shared_secret>
export GITLAB__URL=https://gitlab.com
export OPENAI__KEY=<your_openai_api_key>
export PORT=3000

GitLab Webhookの登録（URL・シークレット・トリガー）

サーバーを起動したら、GitLabのプロジェクト設定でWebhookを登録します。URLはサーバーのホスト名に/webhookを付けたhttps://<PR_AGENT_HOSTNAME>/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の違いで整理しています。

導入時につまずくポイントと対策

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の導入・料金を参照してください。

GitHubで使う場合と設定は違いますか？

基本のコマンド（/reviewなど）は共通ですが、認証やWebhookの登録手順、環境変数の指定はプラットフォームごとに異なります。GitHub側の手順はPR-Agentとは（GitHub版の使い方）にまとめています。

Qodo MergeとPR-Agentは何が違いますか？

PR-Agentはオープンソース版の呼称で、Qodo Merge（Pro）はQodoが提供するホスト版・上位機能を含むサービスです。機能差と選び分けはQodo Merge とはで解説しています。

OpenAI以外のLLMは使えますか？

使えます。PR-Agentはモデルを設定で切り替えられ、OpenAIのほかGoogle Geminiやその他のプロバイダを指定できます。利用するプロバイダに応じてAPIキーの環境変数（例：OPENAI__KEY）を差し替えます。変動が速い領域のため、対応モデルの最新状況は公式ドキュメントで確認してください。