背景

この連載では、Claude Codeの公式ドキュメントを1ページずつ読み解いていきます。公式ドキュメントは情報が網羅されている分、「結局どの機能を、どんな場面で使えばいいのか」は自分で考える必要があり、読むのに意外と時間がかかります。そこで、私が実務で使うために読み込んだ内容を「使う場面→実例コード」の順に整理して残していくことにしました。専門家の解説というより、一次情報を読んだ記録です。推測や動作を確認していない部分には、その都度そう書きます。

一言でいうと何か

Claude Code を GitLab の CI/CD パイプラインに組み込む統合です。第36回の GitHub Actions と対になるもので、issue・MR・レビュースレッドで @claude をメンションすると、GitLab CI/CD が分離ジョブで Claude Code を実行し、コンテキストを集めてプロンプトを組み立て、結果を MR 経由でコミットバックします。プロバイダーは Claude API・Amazon Bedrock・Google Cloud の Agent Platform から選べ、変更はすべて MR を通るためレビューと承認・ブランチ保護がそのまま効きます。なおこの統合はベータ版で、GitLab によって保守されており、サポートは GitLab 側の issue で受け付けられています。

どういう場面で役立つか

GitLab の issue や MR コメントから、実装・修正・MR 作成を任せたいとき。「この issue の説明どおり機能を実装して」「このダッシュボードの TypeError を直して」のように @claude に頼めば、コードベースを分析してブランチに書き込み、レビュー用の MR を開きます。

自前の GitLab パイプライン(GitLab ランナー)で Claude を回したいとき。.gitlab-ci.yml に1ジョブとマスク済み変数を足すだけで始められ、ブランチ保護と承認が AI 生成コードにも適用されます。管理サービスではなく自分の CI インフラで動かしたい場合の選択肢で、成果を MR に集約しつつ既存のパイプラインの中に組み込めます。

Bedrock や GCP を使い、データレジデンシーや調達要件を満たしつつ動かしたいとき。地域エンドポイントを選んでレイテンシ削減とデータ主権要件の両立ができます。

不要・向かないケース：GitHub 側なら GitHub Actions や自動 PR レビューの Code Review が対応します。この統合はベータで GitLab 保守のため、機能は変化しうる点に留意します。コストは GitLab ランナーのコンピュート分と API トークンの両面で発生するため、無制限に走らせる用途には注意が要ります。全体として、GitHub 版と同じ発想を GitLab のパイプラインに移した統合と捉えると分かりやすいです。

セットアップとジョブの実例

前提と仕組み

Claude Code は GitLab CI/CD で AI タスクを分離ジョブとして実行します。GitLab が選んだトリガー(例:@claude を含むコメント)をリッスンし、ジョブがスレッドとリポジトリからコンテキストを集め、プロンプトを構築して Claude Code を実行し、変更を MR に流します。プロバイダーは Claude API(SaaS)・Amazon Bedrock(IAM ベース、クロスリージョン可)・Google Cloud の Agent Platform(GCP ネイティブ、Workload Identity Federation)を抽象化して扱えます。各インタラクションは、厳格なネットワーク/ファイルシステムルールを持つコンテナで動き、Claude Code はワークスペーススコープの権限で書き込みを制限します。

クイックセットアップ(Claude API)

最速の方法は、ANTHROPIC_API_KEY を Settings → CI/CD → Variables にマスク変数(必要に応じて保護)として追加し、.gitlab-ci.yml に最小ジョブを足すことです。

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
  script:
    - /bin/gitlab-mcp-server || true
    - echo "$AI_FLOW_INPUT for $AI_FLOW_CONTEXT on $AI_FLOW_EVENT"
    - >
      claude
      -p "${AI_FLOW_INPUT:-'Review this MR and implement the requested changes'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write mcp__gitlab"
      --debug

rules はトリガー方法(手動実行・MR イベント・@claude コメントでの web/API トリガー)に合わせて調整します。before_script で curl -fsSL https://claude.ai/install.sh | bash により Claude Code を入れ、script では任意で GitLab MCP サーバーを起動し、claude -p にプロンプト(web/API トリガー時はコンテキストペイロードの AI_FLOW_INPUT)を渡します。ジョブと変数を足したら、CI/CD → Pipelines から手動実行するか MR からトリガーしてテストします。

手動セットアップとメンション駆動トリガー

本番向けのより制御されたセットアップでは、まずプロバイダーアクセスを設定します(Claude API なら ANTHROPIC_API_KEY をマスク変数に、Bedrock なら AWS OIDC と IAM ロール、GCP なら Workload Identity Federation)。次に GitLab API 操作用の認証として既定の CI_JOB_TOKEN を使うか、api スコープの Project Access Token を作って GITLAB_ACCESS_TOKEN(マスク)に保存します。そのうえで .gitlab-ci.yml にジョブを追加し、必要ならメンション駆動トリガーを有効化します(プロジェクト webhook に「Comments(notes)」を追加し、コメントに @claude が含まれるときにリスナーがパイプライントリガー API を AI_FLOW_INPUT/AI_FLOW_CONTEXT などの変数付きで呼ぶ構成)。

@claude の使い方

issue コメントや MR ディスカッションで、先頭に指示を書きます。

@claude implement this feature based on the issue description
@claude suggest a concrete approach to cache the results of this API call
@claude fix the TypeError in the user dashboard component

Claude は issue とコードベースを分析して MR を開いたり、キャッシュ実装を提案して MR を更新したり、バグを特定して修正しブランチ更新や新規 MR を行ったりします。このほか、パフォーマンス低下を分析して最適化を提案する、ブランチに直接機能を実装して MR を開く、フォローアップコメントに応答して要求された変更を反復する、といった使い方も想定されています。いずれも成果は MR という形にまとまるため、通常のレビュー手順にそのまま乗せられます。

Amazon Bedrock / Google Cloud での実行

エンタープライズでは同じ開発者体験のまま Bedrock/GCP で動かせます。Bedrock は、Claude モデルへのアクセスを持つ AWS アカウント、AWS IAM に OIDC ID プロバイダーとして構成した GitLab、Bedrock 権限と GitLab プロジェクト/refs に絞った信頼ポリシーを持つ IAM ロール、そして AWS_ROLE_TO_ASSUME/AWS_REGION の CI/CD 変数が必要です。GCP は、Agent Platform API を有効にした GCP プロジェクト、GitLab OIDC を信頼する Workload Identity Federation、必要ロールのみの専用サービスアカウント、GCP_WORKLOAD_IDENTITY_PROVIDER/GCP_SERVICE_ACCOUNT/CLOUD_ML_REGION の変数が必要です。いずれも静的キーを保存せず OIDC/WIF でジョブトークンを一時認証情報と交換する構成で、ジョブ内で aws sts assume-role-with-web-identity や gcloud auth login --cred-file を使います(Bedrock のモデル ID は us.anthropic.claude-sonnet-4-6 のようにリージョンプレフィックス付き)。これらの完全なジョブ YAML は長いため、公式ページの構成例を参照してください。

セキュリティ・コスト・パラメータの要点

API キーやクラウド認証情報はリポジトリにコミットせず、必ず GitLab CI/CD 変数を使い、可能な限りプロバイダー固有の OIDC(長期キーなし)にし、ジョブ権限とネットワーク出力を絞り、Claude の MR も他の貢献者と同じようにレビューします。各ジョブはネットワーク制限された分離コンテナで動き、変更は MR を通るのでレビュアーが全 diff を確認でき、承認・ブランチ保護が AI 生成コードにも適用されます。コストは GitLab ランナー時間と API トークンの両面で、@claude を具体的にする・max_turns やジョブタイムアウトを適切に設定する・並列実行を制限する、といった最適化が推奨されます。よく使う入力は prompt/prompt_file(-p かファイルで指示)、max_turns、timeout_minutes、ANTHROPIC_API_KEY(Claude API 必須、Bedrock/GCP では未使用)などで、正確なフラグはバージョンにより異なるためジョブで claude --help を確認します。@claude に応答しないときは、パイプラインがトリガーされているか・CI/CD 変数が存在しマスク解除されているか・コメントが /claude でなく @claude か、を確認します。

まとめ

GitLab CI/CD 統合は、@claude メンションから実装・修正・MR 作成までを GitLab のパイプラインで回せる、GitHub Actions の GitLab 版です(ベータ、GitLab 保守)。導入は Claude API なら ANTHROPIC_API_KEY をマスク変数に入れて .gitlab-ci.yml に1ジョブ追加が最速で、curl ...install.sh | bash で Claude Code を入れ、claude -p ... --permission-mode acceptEdits --allowedTools "... mcp__gitlab" を実行します。Bedrock/GCP では OIDC/WIF で静的キーなしに認証し、変更は MR を通るためレビューと承認・ブランチ保護がそのまま効きます。コストは GitLab ランナー時間と API トークンの両面、という点を押さえておくとよいでしょう。

次回は、残る連携ページ(GitHub Enterprise Server など)や Channels・/goal・Agent SDK などの未執筆ページ、あるいは長く保留している引き継ぎ課題(第5回欠番の補完・第1/2回の照合)に着手する予定です。

---

この記事は執筆時点の公式ドキュメントに基づいています。最新の情報は必ず公式ドキュメントをご確認ください。