Claude Media
Claude CodeとGitLab CI/CDの連携 — @claudeメンションでMRを自動化

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. 1

    コメントを書く

    IssueかMRのコメントに@claudeを含めて依頼を書きます。

  2. 2

    Webhookで通知する

    プロジェクトに「Comments (notes)」のWebhookを登録し、イベントを受けるリスナーへ送ります。

  3. 3

    リスナーがトリガーAPIを呼ぶ

    コメントに@claudeが含まれていれば、AI_FLOW_INPUTとAI_FLOW_CONTEXTを変数に付けてパイプライントリガーAPIを呼びます。

  4. 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版

Anthropic提供のclaude-code-action

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社が保守するベータ

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)で追えます。

参照した一次ソース

この記事の記述は、次の一次ソースと照合しています。更新時に参照先が変わった場合は一覧も更新します。

  1. code.claude.com/docs/en/gitlab-ci-cd
  2. gitlab.com/gitlab-org/gitlab/-/issues/573776
  3. code.claude.com/docs/en/agent-sdk/overview
  4. code.claude.com/docs/en/cli-reference
  5. code.claude.com/docs/en/github-actions
この記事を共有:XはてブLinkedIn