Claude Media
Claude CodeをGitLab CI/CDに組み込む — @claudeメンションでMR自動化
Claude Codeチュートリアル

Claude CodeをGitLab CI/CDに組み込む — @claudeメンションでMR自動化

GitLab CI/CDのジョブとしてClaude Codeを動かし、Issue/MRコメントの@claudeメンションから実装・修正・MR作成までを自動化する設定手順とコスト管理をまとめます。

読了目安 約12分

はじめに

GitLab CI/CDのパイプラインにジョブを1つ足すだけで、Issueのコメントに@claude implement this featureと書くだけでMRが上がってくる仕組みを作れます。GitLab CI/CDでのClaude Code連携は、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

ステップ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: 本番向けの認証設計

本番運用では「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としてマスク登録します。

認証情報の取り扱いやサンドボックス実行の考え方はClaude Codeセキュリティ・権限ガイドの原則がそのまま当てはまります。@claudeメンションでの起票をIssueやMRコメントから拾いたい場合は、「Comments (notes)」のWebhookをリスナーに登録します。コメントに@claudeが含まれるときに、AI_FLOW_INPUTやAI_FLOW_CONTEXT変数付きでパイプライントリガーAPIを呼び出す構成にします。この部分はGitLab側のWebhook基盤を使う自前実装が必要です。クイックセットアップのように既製の仕組みは用意されていません。

公式のSecurity considerationsでは、ジョブに与える権限とネットワーク送信先を必要最小限に絞り込むことが求められています。ジョブトークンやProject Access Tokenのスコープを実際に必要な範囲に限定し、ジョブが到達できる外部エンドポイントも用途に応じて制限してください。また、Claudeが作成したMRであっても通常のMRと同じレビュー・承認フローを通す運用が前提です。自動化されているからといって承認プロセスを省略しないでください。

ステップ3: Amazon BedrockまたはGoogle Cloudで動かす

エンタープライズ環境では、静的なAPIキーを持たずに動かす構成が現実的です。Amazon Bedrockの場合、GitLabをAWS IAMのOIDCプロバイダーとして設定し、GitLabプロジェクト・保護されたrefに制限したIAMロールを用意します。ジョブはid_tokens:ブロックでOIDCトークンを取得し、sts assume-role-with-web-identityで一時的なAWS認証情報に交換します。

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で同様の仕組みを組みます。GitLabのOIDCトークンをファイルに書き出し、credential_sourceでその場所を指すクレデンシャル設定ファイルを用意します。これをGOOGLE_APPLICATION_CREDENTIALSとして渡すだけです。どちらの構成もサービスアカウントキーのダウンロードが不要で、信頼関係をプロジェクト・ref単位に絞り込めます。

コストを見積もる

GitLab CI/CDでClaude Codeを動かすと、2種類のコストが発生します。GitLab Runnerの実行時間(プランのRunner課金に従う)と、Claudeへのリクエストごとのトークン消費です。トークン消費量はタスクの複雑さとコードベースの規模で変動するため、事前に固定額で見積もるのは困難です。Claude APIの料金体系そのものはClaude Codeの料金ガイドを参照してください。Bedrock経由での単価差はBedrockのClaude料金にまとめています。

コストを抑える実務上の工夫は3つあります。@claudeコマンドを具体的に書いて不要なターン数を減らすこと。--max-turnsとジョブのtimeoutキーワードで上限を設定すること。そして、同時実行数を制限して並列ジョブが増えすぎないようにすることです。

GitLab版はGitHub Actions版と何が違うか

同じ「PRやMRのコメントから起動する」体験でも、提供元と成熟度は異なります。GitHub Actions版のclaude-code-action@v1はAnthropicが直接メンテナンスする1.0世代の製品です。一方GitLab CI/CD版は、GitLab社が保守するベータ機能です。サポートもGitLabのissueトラッカー経由になります。

もう一つの違いは、メンション起動の組み込み度です。GitHub Actions版の認証・コスト設計では、OAuthトークンかAPIキーを登録するだけでPRコメントやIssueイベントを標準でトリガーに使えます。対してGitLab版で@claudeメンションを拾うには、コメントWebhookをリスナーで受けてパイプライントリガーAPIを呼ぶ自前の橋渡しが要ります。導入の手間だけを見ればGitHub Actions版のほうが少なく、GitLabを使っているという理由だけで無理に本統合を選ぶ必要はありません。GitLabが主戦場のチームにとっては、この手間を払ってでも同じ体験をGitLab上で完結できる価値があります。

Claudeの振る舞いをカスタマイズする

ジョブの挙動は2つの方法で調整できます。1つはリポジトリルートに置くCLAUDE.mdで、コーディング規約やレビュー基準、プロジェクト固有のルールを書いておくと、Claudeは実行中にそれを読んで従います。もう1つはジョブの-pフラグに渡すプロンプトそのもので、レビュー用・実装用・リファクタリング用のように用途別にジョブを分け、それぞれ異なる指示文を渡す構成が扱いやすくなります。CLAUDE.mdは簡潔に保ち、Issue・MRの説明文自体を具体的に書くことが、余計な往復ターンを減らす一番の近道です。

よくあるつまずき

@claudeにジョブが反応しない場合、まずパイプラインが実際にトリガーされているか(手動実行、MRイベント、Webhookリスナー経由)を確認します。次にコメントが@claude(/claudeではない)を含んでいるか、メンショントリガーの設定が正しいかを見直します。

ジョブがコメントを書けない、MRを開けない場合は、CI_JOB_TOKENの権限がプロジェクトに対して十分かを確認します。またはapiスコープ付きのProject Access Tokenを使っているかも見直してください。--allowedToolsにmcp__gitlabが含まれているかも見落としやすいポイントです。

Bedrock/Vertexで認証エラーになる場合は、OIDC/WIFの設定、ロールの権限借用(impersonation)、シークレット名の一致を確認します。リージョンとモデルの組み合わせが利用可能かどうかも合わせて確認してください。

まとめ

GitLabでコードを管理しているチームがClaude CodeをCI/CDに組み込む場合、進め方は2段階に分けると現実的です。まずクイックセットアップでANTHROPIC_API_KEYとジョブ1つの動作を確認します。本番運用に進む段階で、OIDC/WIFベースの認証と@claudeメンショントリガーの橋渡しを整えます。GitLab社が保守するベータ機能である点を踏まえ、仕様変更の情報はGitLab側のissueトラッカーも合わせて追うと安心です。動かし始める前にRunner時間とトークン消費の両方が課金対象になる点を頭に入れておくと、想定外の請求に驚かずに済みます。

よくある質問

GitLab CI/CD版はAnthropicが直接サポートしていますか

いいえ。この統合はGitLab社が保守しており、サポートもGitLabのissueトラッカーが窓口です。Claude Code CLIとAgent SDKの上に構築されています。

静的なAPIキーを使わずに運用できますか

できます。Amazon BedrockはAWS OIDC、Google CloudのAgent PlatformはWorkload Identity Federationという仕組みが使えます。どちらもサービスアカウントキーを保存せず、一時的な認証情報でジョブを実行できます。

CI_JOB_TOKENとProject Access Tokenはどう使い分けますか

既定ではCI_JOB_TOKENで足りるケースが多いです。権限が不足する場合はapiスコープ付きのProject Access Tokenを発行し、マスク付き変数GITLAB_ACCESS_TOKENとして登録する構成が案内されています。

GitHub Actions版からの移行に使い回せる知識はありますか

CLAUDE.mdによるコーディング規約の指定や、タスク別にプロンプトを使い分ける考え方はそのまま使い回せます。一方でトリガーの仕組みはGitLab側のWebhookとパイプライントリガーAPIに置き換える必要があり、ワークフロー定義自体の互換性はありません。

claude --helpで確認できるフラグはすべて使えますか

@anthropic-ai/claude-codeのバージョンによって対応フラグが変わります。ジョブの中で実際にclaude --helpを実行し、その時点でサポートされているオプションを確認するのが確実です。ドキュメントに載っているフラグ名も将来変わる可能性があります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →