Claude Code を GitLab CI/CD で動かす

Issue に「@claude この機能を実装して」とコメントすると、GitLab のパイプラインで Claude Code が動き、変更をブランチに書いてマージリクエスト（MR）を開く。Claude Code GitLab CI/CD はこうした使い方を .gitlab-ci.yml のジョブ1つで実現する連携です。本記事では公式ドキュメント「Claude Code GitLab CI/CD」に沿って、仕組み・最小構成のジョブ・クラウドプロバイダでの認証・運用上の注意を日本語で整理します。

公式ドキュメントによると、この連携はベータ版で、機能は今後変わる可能性があります。また保守しているのは GitLab 側で、サポート窓口は GitLab の Issue です。GitHub 向けの Claude CodeをGitHub Actionsで動かすと発想は近いものの、設定方法は別物なので混同しないようにしてください。

GitLab 連携でできること

この連携は Claude Code CLI と Agent SDK の上に作られており、CI/CD ジョブの中で Claude をプログラムから呼び出します。処理の流れは公式ドキュメントで次の3段階として説明されています。

イベント駆動の起動: Issue・MR・レビュースレッドで @claude を含むコメントが付くなど、選んだトリガーで GitLab がジョブを起動します。ジョブはスレッドとリポジトリから文脈を集めてプロンプトを組み立て、Claude Code を実行します。
プロバイダの選択: Claude API、Amazon Bedrock（IAM ベースのアクセス）、Google Cloud の Agent Platform（Workload Identity Federation）から環境に合うものを使えます。リージョンのエンドポイントを選べば、レイテンシやデータ所在の要件にも合わせられます。
隔離された実行: 各処理はネットワークとファイルシステムを制限したコンテナで動き、書き込みはワークスペースの範囲に限定されます。変更はすべて MR を通るため、レビュアーが差分を確認し、既存の承認ルールもそのまま効きます。

パイプラインの中で Claude ができることとして、公式には次の例が挙がっています。

Issue の説明やコメントから MR を作成・更新する
性能の劣化を分析して最適化を提案する
ブランチ上で機能を実装し、MR を開く
テストやコメントで指摘されたバグを修正する
追加のコメントに応答して変更を繰り返し調整する

Claude はリポジトリの CLAUDE.md と既存コードのパターンに従って作業します（CLAUDE.md については CLAUDE.md で Claude Code にプロジェクトを記憶させるを参照）。

クイックセットアップ

最短の始め方は、API キーをマスク変数として登録し、.gitlab-ci.yml に最小限のジョブを足すことです。

マスクされた CI/CD 変数を追加する: Settings → CI/CD → Variables を開き、ANTHROPIC_API_KEY を追加します（必要に応じて protected にもします）。
.gitlab-ci.yml に Claude のジョブを追加する: 公式ドキュメントに掲載されている例は次のとおりです。

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  # ジョブの起動条件は用途に合わせて調整する
  # - 手動実行
  # - マージリクエストのイベント
  # - '@claude' を含むコメントを受けた web/API トリガー
  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
    # インストーラは claude を ~/.local/bin に置くが、このイメージでは PATH に入っていない
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    # 任意: 環境に GitLab MCP サーバーがあれば起動する
    - /bin/gitlab-mcp-server || true
    # web/API トリガーで文脈を渡すときは AI_FLOW_* 変数を使う
    - 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

ポイントは3つです。まず claude -p で指示を渡す非対話の実行（Claude Codeをヘッドレス（非対話）で実行する）であること。次に --permission-mode acceptEdits でファイル編集を自動承認していること（Manual・Plan・Autoをどう選ぶ？ Claude Code権限モードの使い分け）。そして --allowedTools で使えるツールを Bash・Read・Edit・Write と GitLab 用 MCP ツール mcp__gitlab に絞っていることです。

ジョブと変数を追加したら、CI/CD → Pipelines から手動でジョブを実行して試すか、MR からトリガーして Claude にブランチ上で変更を提案させます。

本番向けの手動セットアップ

より管理された構成やエンタープライズ向けプロバイダが必要な場合、公式ドキュメントは次の手順を推奨しています。

プロバイダへのアクセスを設定する
- Claude API: ANTHROPIC_API_KEY をマスクされた CI/CD 変数として保存する
- Amazon Bedrock: GitLab を AWS の OIDC として設定し、Bedrock 用の IAM ロールを作る
- Google Cloud の Agent Platform: GitLab 向けに Workload Identity Federation を設定する
GitLab API 操作用の認証情報を用意する: 既定では CI_JOB_TOKEN を使います。足りなければ api スコープの Project Access Token を作り、GITLAB_ACCESS_TOKEN（マスク）として保存します。
ジョブを追加する: Claude API なら前節のジョブ、クラウドプロバイダなら次節の例を使います。
（任意）メンションでの起動を有効にする: 「Comments (notes)」のプロジェクト Webhook を自前のイベントリスナーに向け、コメントに @claude が含まれていたらパイプライントリガー API を AI_FLOW_INPUT や AI_FLOW_CONTEXT などの変数付きで呼ぶようにします。

つまり、@claude のメンションに反応させる部分は GitLab 標準の Webhook とパイプライントリガーを組み合わせて自分で用意する形です。設定後は、たとえば次のようなコメントで使います（公式の例を和訳）。

Issue で「@claude implement this feature based on the issue description」（Issue の説明に基づいて実装）: Claude が Issue とコードを分析し、ブランチに変更を書いて MR を開きます。
MR の議論で「@claude suggest a concrete approach to cache the results of this API call」（API 呼び出し結果のキャッシュ方法を提案）: 変更案を示し、MR を更新します。
Issue や MR で「@claude fix the TypeError in the user dashboard component」（TypeError の修正）: バグを特定して修正し、ブランチを更新するか新しい MR を開きます。

Amazon Bedrock と Google Cloud で動かす

エンタープライズ環境では、同じ使い勝手のまま自社のクラウド基盤上で Claude Code を動かせます。どちらも長期間有効なキーを保存せず、ジョブが発行する OIDC トークンを一時的な認証情報に交換する方式です。

Amazon Bedrock（OIDC）

前提は、目的の Claude モデルにアクセスできる Bedrock、AWS IAM に OIDC プロバイダとして登録した GitLab、そしてプロジェクトと保護された ref に絞った信頼ポリシーと最小権限を持つ IAM ロールです。CI/CD 変数として AWS_ROLE_TO_ASSUME（ロールの ARN）と AWS_REGION を用意します。

ジョブでは id_tokens: ブロックで GITLAB_OIDC_TOKEN を発行させ（aud は AWS 側に設定した audience と合わせる）、aws sts assume-role-with-web-identity で一時認証情報に交換してから、CLAUDE_CODE_USE_BEDROCK: "1" を設定して claude -p を実行します。公式の例から要点を抜き出すと次のとおりです。

claude-bedrock:
  stage: ai
  image: node:24-alpine3.21
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.example.com
  before_script:
    - apk add --no-cache bash curl jq git aws-cli
    - curl -fsSL https://claude.ai/install.sh | bash
    - export PATH="$HOME/.local/bin:$PATH"
    - export AWS_WEB_IDENTITY_TOKEN_FILE="/tmp/oidc_token"
    - printf "%s" "$GITLAB_OIDC_TOKEN" > "$AWS_WEB_IDENTITY_TOKEN_FILE"
    - >
      aws sts assume-role-with-web-identity
      --role-arn "$AWS_ROLE_TO_ASSUME"
      --role-session-name "gitlab-claude-$(date +%s)"
      --web-identity-token "file://$AWS_WEB_IDENTITY_TOKEN_FILE"
      --duration-seconds 3600 > /tmp/aws_creds.json
    # AccessKeyId / SecretAccessKey / SessionToken を jq で取り出して export する
  variables:
    AWS_REGION: "us-west-2"
    CLAUDE_CODE_USE_BEDROCK: "1"

Bedrock のモデル ID には us.anthropic.claude-sonnet-4-6 のようにリージョンの接頭辞が付く点にも注意します。

Google Cloud の Agent Platform（Workload Identity Federation）

前提は、Agent Platform API を有効にしたプロジェクト、GitLab の OIDC を信頼する Workload Identity Federation、必要なロールだけを持つ専用サービスアカウントです。CI/CD 変数として GCP_WORKLOAD_IDENTITY_PROVIDER（//iam.googleapis.com/ を除いたプロバイダのリソース名）、GCP_SERVICE_ACCOUNT、GCP_PROJECT_ID、CLOUD_ML_REGION（例: us-east5）を用意します。

ジョブは OIDC トークンをファイルに書き出し、それを credential_source として参照する external_account 形式の認証情報設定ファイルを生成します。そのファイルを GOOGLE_APPLICATION_CREDENTIALS に指定すると、Application Default Credentials 経由で Claude Code が認証情報を使えます。あわせて CLAUDE_CODE_USE_VERTEX: "1" と ANTHROPIC_VERTEX_PROJECT_ID を設定します。サービスアカウントキーを保存する必要はありません。

いずれのプロバイダでも、Claude Code 側の設定は通常のクラウド利用と同じです。詳しくは Claude Code を Amazon Bedrock で使うと Claude Code を Google Cloud の Agent Platform で動かすも参照してください。

運用のベストプラクティスとトラブルシューティング

設定とセキュリティ

CLAUDE.md: リポジトリのルートにコーディング規約・レビュー基準・プロジェクト固有のルールを書きます。Claude は実行時にこれを読んで従います。短く要点を絞るほうが性能面でも有利です。
API キーやクラウドの認証情報をリポジトリにコミットしない: 必ず GitLab の CI/CD 変数を使い、可能ならプロバイダの OIDC で長期キーをなくします。
ジョブの権限とネットワークの出口を制限し、Claude の MR は他のコントリビューターと同じようにレビューします。
Issue や MR の説明を明確に書くと、やり取りの往復が減ります。ランナーでは npm などのパッケージインストールをキャッシュします。

コスト

費用は2種類かかります。Claude は自分の GitLab ランナー上で動くのでランナーの計算時間を消費し、各処理はプロンプトと応答の大きさに応じたトークンを消費します。公式の節約策は、具体的な @claude の指示で無駄なターンを減らす、--max-turns とジョブの timeout（例: timeout: 30m）を適切に設定する、並列実行数を制限する、の3つです。料金の考え方はコストを効果的に管理するも参考になります。

よくあるトラブル

症状	確認すること
`@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 なら OIDC/WIF の設定、ロールの引き受け、変数名、リージョンとモデルの提供状況。

使えるフラグや引数は Claude Code のバージョンで変わることがあるため、公式はジョブ内で claude --help を実行して確認するよう勧めています。ジョブごとに -p のプロンプトを変えれば、レビュー用・実装用・リファクタリング用といった使い分けもできます。

本記事は Anthropic 公式ドキュメント「Claude Code GitLab CI/CD」に基づく非公式の日本語解説です（確認日 2026-09-17）。この連携はベータ版で GitLab が保守しているため、最新の手順は公式ページで確認してください。