Claude CodeとGitLab CI/CDの連携 — @claudeメンションでMRを自動化
Claude CodeをGitLab CI/CDのジョブで動かす公式の経路を扱います。設定手順、@claudeメンションの仕組み、mcp__gitlabの扱い、コスト上限を説明します。
はじめに
Claude CodeをGitLab CI/CDで動かす公式の経路は、GitLab社が保守するベータ版の統合です。.gitlab-ci.ymlにジョブを1つと、マスク付きのAPIキー変数を1つ足せば動きます。
手元の対話セッションでMRからワークツリーを切る連携や、glabを使う連携はClaude Code GitLab連携ガイドにまとめています。ここではCI/CDジョブとして動かす連携を扱います。
Issueのコメントに@claude implement this featureと書いてMRを上げさせる使い方も対象です。この連携は、Claude Code CLIとAgent SDKの上に構築されています。
前提条件は次の3つです。
| 項目 | 必要な状態 |
|---|---|
| GitLabプロジェクト | 必要な状態.gitlab-ci.ymlを編集できる権限 |
| API認証 | 必要な状態Claude APIキー、またはAmazon Bedrock/Google Cloudの認証情報 |
| GitLab側の認証 | 必要な状態CI_JOB_TOKENまたはapiスコープ付きProject Access Token |
GitLabとClaude Codeをつなぐ3つの経路
「GitLab連携」で探すとき、読者が求めている中身は3通りに分かれます。
| やりたいこと | 経路 | 参照先 |
|---|---|---|
| IssueやMRのコメントからMRを作らせたい | 経路CI/CDジョブ + Webhookリスナー(ジョブ内ではmcp__gitlabツールを使う) | 参照先この記事のステップ1〜3 |
| 手元の対話セッションでMRを扱いたい | 経路ローカルのMR分岐・glab CLI | 参照先Claude Code GitLab連携ガイド |
| MRの状況を手元のClaude Codeで見たい | 経路プロンプトフッターのMRバッジ | 参照先PRレビューステータスの見方 |
ステップ1: クイックセットアップで動かす
最短経路は、マスク付きCI/CD変数を1つ登録し、.gitlab-ci.ymlにジョブを1つ足すことです。Settings → CI/CD → VariablesからANTHROPIC_API_KEYをマスク(必要なら保護)付きで追加します。
続けて次のジョブを追加します。
stages:
- ai
claude:
stage: ai
image: node:24-alpine3.21
rules:
- if: '$CI_PIPELINE_SOURCE == "web"'
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
variables:
GIT_STRATEGY: fetch
before_script:
- apk update
- apk add --no-cache git curl bash
- curl -fsSL https://claude.ai/install.sh | bash
- export PATH="$HOME/.local/bin:$PATH"
script:
- /bin/gitlab-mcp-server || true
- >
claude
-p "${AI_FLOW_INPUT:-'Review this MR and implement the requested changes'}"
--permission-mode acceptEdits
--allowedTools "Bash Read Edit Write mcp__gitlab"
--debugインストーラーは~/.local/binにclaudeを置きますが、このイメージではPATHに入っていないため、export PATHの行が必須です。追加後はCI/CD → Pipelinesから手動実行するか、MRからトリガーして動作を確認します。
コピーしたジョブで先に直しておく2点
このジョブは公式サンプルのままでは、意図と違う動きをする箇所が2つあります。1つ目はデフォルトのプロンプトです。${AI_FLOW_INPUT:-'Review this MR ...'}は、変数が空のときの既定値を単一引用符で囲んでいます。ダブルクォートの内側の単一引用符は文字として残るため、引用符付きの文字列がそのままプロンプトになります。手元のシェルで確かめた結果は次のとおりです。
unset AI_FLOW_INPUT
bash -c 'echo "[${AI_FLOW_INPUT:-'"'"'Review this MR'"'"'}]"'
sh -c 'echo "[${AI_FLOW_INPUT:-Review this MR and implement the requested changes}]"'['Review this MR']
[Review this MR and implement the requested changes]引用符が残っても動作はしますが、意図しない文字がプロンプトに混ざります。:-の右側は引用符を付けずに書くほうが素直です。
2つ目は許可ツールです。--allowedToolsは、プロンプトなしで実行されるツールを列挙するフラグで、claude --helpではカンマか空白区切りとされています(v2.1.285で確認)。ヘルプの例が"Bash(git *) Edit"であるように、Bashは引数のパターンで絞れます。サンプルはBashをそのまま許可しているので、CIで触らせたくないコマンドがあるならBash(git *)のように範囲を狭めます。
ジョブのmcp__gitlabは何を指すか
mcp__gitlabは、GitLabという名前のMCPサーバーが提供するツールを許可する名前です。サンプルの/bin/gitlab-mcp-server || trueは、サーバーを起動できなければ読み飛ばして先へ進みます。
公式サンプルのコメントは、この行を「GitLab MCPサーバーを、環境が用意している場合の任意の手順」としています。node:24-alpine3.21のイメージにこのコマンドが入っているとは限らず、無ければサーバーは起動せず、許可したツールも使えません。公式サンプルは/bin/gitlab-mcp-serverの提供元を示していません。MRの作成やコメント投稿までジョブに任せるなら、その手段(MCPサーバーか、GITLAB_ACCESS_TOKENを使ったAPI呼び出し)を自分の環境で用意できているかを先に確かめます。
ステップ2: 本番向けの認証設計
本番運用向けには、「Manual setup」と呼ばれる、より制御しやすい構成が公式で推奨されています。まずプロバイダ側の認証を選びます。
| プロバイダ | 認証方式 | 向くケース |
|---|---|---|
| Claude API | 認証方式マスク付きCI/CD変数ANTHROPIC_API_KEY | 向くケース個人開発・小規模チーム、最短導入 |
| Amazon Bedrock | 認証方式AWS OIDC + IAMロール(静的キー不要) | 向くケースAWSにデータレジデンシー要件があるエンタープライズ |
| Google CloudのAgent Platform | 認証方式Workload Identity Federation(WIF) | 向くケースGCPネイティブ環境、GCP契約を活かしたい組織 |
次に、GitLab API操作用の認証を決めます。既定はCI_JOB_TOKENです。権限が足りなければapiスコープ付きのProject Access Tokenを発行し、GITLAB_ACCESS_TOKENとしてマスク登録します。Google Cloud側は4変数が公式ジョブ例の前提です。GCP_WORKLOAD_IDENTITY_PROVIDER(先頭の//iam.googleapis.com/を除いたプロバイダ名)とGCP_SERVICE_ACCOUNTです。残りはGCP_PROJECT_IDとCLOUD_ML_REGIONです。
認証情報の取り扱いやサンドボックス実行の考え方はClaude Codeセキュリティ・権限ガイドの原則がそのまま当てはまります。コメントの@claudeをジョブにつなぐ流れは、クイックセットアップのジョブには含まれません。次の4段階になります。
コメントの@claudeがジョブになるまで
- 1
コメントを書く
IssueかMRのコメントに
@claudeを含めて依頼を書きます。 - 2
Webhookで通知する
プロジェクトに「Comments (notes)」のWebhookを登録し、イベントを受けるリスナーへ送ります。
- 3
リスナーがトリガーAPIを呼ぶ
コメントに
@claudeが含まれていれば、AI_FLOW_INPUTとAI_FLOW_CONTEXTを変数に付けてパイプライントリガーAPIを呼びます。 - 4
ジョブがclaudeを実行する
ジョブは
AI_FLOW_INPUTを-pに渡してClaude Codeを動かし、結果をMRとして返します。
リスナーはGitLabの標準機能ではありません。自分で書くか、既存のWebhook基盤に載せます。
公式のSecurity considerationsが挙げるのは4点です。1点目はAPIキーをマスク付き変数に置くこと、2点目は可能ならプロバイダのOIDCで長期キーを避けることです。3点目はジョブの権限とネットワーク送信を絞ること、4点目はClaudeのMRを他のコントリビューターと同じようにレビューすることです。ジョブトークンやProject Access Tokenのスコープも、実際に使う範囲に留めます。
ステップ3: Amazon BedrockまたはGoogle Cloudで動かす
エンタープライズ環境では、静的なAPIキーを持たずに動かす構成が現実的です。Amazon Bedrockの場合、GitLabをAWS IAMのOIDCプロバイダーとして設定し、GitLabプロジェクト・保護されたrefに制限したIAMロールを用意します。Bedrockのモデル名にはリージョン別のプレフィックスが付きます(例: us.anthropic.claude-sonnet-4-6)。ジョブはid_tokens:ブロックでOIDCトークンを取得し、sts assume-role-with-web-identityで一時的なAWS認証情報に交換します。CI/CD変数としてAWS_ROLE_TO_ASSUME(ロールARN)とAWS_REGIONを用意します。audには、AWS側のIAM OIDCプロバイダに設定した値(GitLabのURLなど)を入れます。
id_tokens:
GITLAB_OIDC_TOKEN:
aud: https://gitlab.example.com
variables:
AWS_REGION: "us-west-2"
CLAUDE_CODE_USE_BEDROCK: "1"Google CloudのAgent Platformを使う場合はWorkload Identity Federationで同様の仕組みを組みます。事前にIAM Credentials API、STS API、Agent Platform APIを有効にします。ジョブ側にはCLAUDE_CODE_USE_VERTEX: "1"と、プロジェクトIDを渡すANTHROPIC_VERTEX_PROJECT_IDを指定します。GitLabのOIDCトークンをファイルに書き出し、credential_sourceでその場所を指すクレデンシャル設定ファイルを用意します。これをGOOGLE_APPLICATION_CREDENTIALSに指定すると、Claude CodeがApplication Default Credentials経由で使います。公式のジョブ例は、同じ設定ファイルでgcloud auth loginも行っています。どちらの構成もサービスアカウントキーのダウンロードが不要で、信頼関係をプロジェクト・ref単位に絞り込めます。IAMロールのトラストポリシーやジョブYAMLの実装単位まで踏み込んだ手順はClaude CodeのBedrock OIDC認証をGitLab CI/CDで組むにまとめています。
コストを見積もる
GitLab CI/CDでClaude Codeを動かすと、2種類のコストが発生します。GitLab Runnerの実行時間(プランのRunner課金に従う)と、Claudeへのリクエストごとのトークン消費です。トークン消費量はタスクの複雑さとコードベースの規模で変動するため、事前に固定額で見積もるのは困難です。Claude APIの料金体系そのものはClaude Codeの料金ガイドを参照してください。Bedrock経由での単価差はBedrockのClaude料金にまとめています。
上限をかける手段は3つあります。--max-turns(往復の上限)、ジョブのtimeoutキーワード、同時実行数の制限です。--max-turnsは公式のcli-referenceで「printモード専用で、上限に達するとエラー終了、既定は無制限」と説明されています。ただし手元のv2.1.285ではclaude --helpにこのフラグが出ません。CIのYAMLに書く前に、ジョブの中でclaude --helpを実行して自分の環境の表示を確かめると安全です。
金額で止めたいときは--max-budget-usdが使えます。これもprintモード専用で、サブエージェントの消費も上限に数えられます。上限に達した後のサブエージェント起動を止める挙動はv2.1.217以降の仕様です。
claude -p --max-turns 5 --max-budget-usd 2.00 "Review this MR"コマンドの書式はcli-referenceの例に沿っています。@claudeのコマンドを具体的に書いて余計なターンを減らすことも、費用に効きます。あわせて、Runnerではnpmなどのパッケージのインストールをキャッシュすると実行時間を縮められます。
GitLab版はGitHub Actions版と何が違うか
同じ「コメントから起動する」体験でも、提供元と@claudeを拾う仕組みが違います。
GitHub Actions版とGitLab CI/CD版
GitHub Actions版
GitHub Actions版の認証・コスト設計では、.github/workflows/にサンプルのclaude.ymlを置くと、IssueやPRのコメントの@claudeにそのまま反応します。認証はANTHROPIC_API_KEYかサブスクリプションのCLAUDE_CODE_OAUTH_TOKENです。IssueやPRのイベントでは、起動するユーザーに書き込み権限が必要です(allowed_non_write_usersで例外を指定できます)。Botのトリガーは既定で弾かれます。
GitLab CI/CD版
@claudeを拾うのはジョブではなく、Webhookを受けるリスナーです。認証はAPIキーのほか、BedrockのOIDCやGoogle CloudのWIFが選べます。
リポジトリがGitHubにあるなら、GitHub Actions版のほうが少ない手間で同じ体験を得られます。GitLabでホストしているなら選択肢はこの統合で、差分になるのはリスナーの実装です。GitLab内蔵のエージェント基盤との違いはClaude CodeとGitLab Duo Agent Platformの比較にあります。
ジョブの挙動を変える
挙動を決める入口は2つです。リポジトリ直下のCLAUDE.mdにコーディング規約とレビュー基準を書くと、実行中に読まれます。もう1つはジョブの-pに渡す指示文で、レビュー用・実装用・リファクタリング用にジョブを分けて別々の指示を渡せます。CLAUDE.mdは短く保ち、Issueの説明文を具体的に書くほうが往復は減ります。
よくあるつまずき
@claudeにジョブが反応しない場合、まずパイプラインが実際にトリガーされているか(手動実行、MRイベント、Webhookリスナー経由)を確認します。次にANTHROPIC_API_KEYかクラウド側の変数が入っているか、コメントが@claude(/claudeではない)を含んでいるかを見ます。
ジョブがコメントを書けない、MRを開けない場合は、CI_JOB_TOKENの権限がプロジェクトに対して十分かを確認します。またはapiスコープ付きのProject Access Tokenを使っているかも見直してください。--allowedToolsにmcp__gitlabが含まれているかも見落としやすいポイントです。ジョブがMRの文脈で動いているか、AI_FLOW_*変数で十分な文脈が渡っているかも確認します。
認証エラーになる場合、Claude APIではANTHROPIC_API_KEYが有効で期限切れでないかを見ます。BedrockとGoogle CloudのAgent Platformでは、OIDC/WIFの設定とロールの権限借用(impersonation)を確認します。加えて、シークレット名の一致と、リージョンでのモデルの利用可否も見ます。
テストやビルドなど、Claude以外のジョブが落ちたときの切り分けはGitLab CIの失敗ジョブをglabで調べる手順にあります。
まとめ
MRイベントや手動実行で足りるなら、マスク付き変数とジョブ1つで始められます。メンション起動はリスナーを用意できてから足せば足ります。ベータの仕様変更はGitLab側のissue(573776)で追えます。
参照した一次ソース
この記事の記述は、次の一次ソースと照合しています。更新時に参照先が変わった場合は一覧も更新します。