GitLab CI/CD

GitLab CI/CD の隔離されたジョブで Claude Code を動かし、結果をマージリクエスト（MR）として返す連携です。イシューや MR のコメントで @claude と書く（または手動・API で起動する）と、Claude が文脈を集め、変更をブランチに書き、MR を開きます。この連携は Claude Code の CLI と Agent SDK の上に作られています。

• イシューの説明から MR を作る、MR で実装の案を出す、テストやコメントで見つかったバグを直す、といった作業ができる
• .gitlab-ci.yml にジョブを1つと、マスクした CI/CD 変数を足せば始められる
• CLAUDE.md の指針と既存のコードのパターンに従う
• Claude API・Amazon Bedrock・Google Cloud の Agent Platform から選べる（データの所在地や調達の要件に合わせる）
• 自分の GitLab ランナーで、ブランチの保護と承認を保ったまま動く

しくみ#

Claude Code は、GitLab CI/CD で AI の作業を隔離されたジョブで動かし、結果を MR としてコミットし直します。

1. イベント駆動の調整：GitLab が選んだトリガー（イシュー・MR・レビューのスレッドで @claude に言及するコメントなど）を待つ。ジョブはスレッドとリポジトリから文脈を集め、その入力からプロンプトを組み立て、Claude Code を動かす
2. プロバイダーの切り替え：環境に合うものを使う（Claude API の SaaS、IAM ベースのアクセスとクロスリージョンの選択肢がある Amazon Bedrock、GCP ネイティブで Workload Identity Federation を使う Google Cloud の Agent Platform）
3. サンドボックスでの実行：各やり取りは、ネットワークとファイルシステムに厳しい規則のあるコンテナで動く。Claude Code は、ワークスペースに限った権限で書き込みを制限する。すべての変更は MR を通るので、レビュアーは差分を見られ、承認も適用される

地域のエンドポイントを選べば、既存のクラウド契約を使いながら、遅延を減らし、データ主権の要件を満たせます。GitLab のパイプラインで Claude ができることは次のとおりです。

• イシューの説明やコメントから、MR を作成・更新する
• 性能の退行を分析し、最適化を提案する
• ブランチに直接機能を実装し、MR を開く
• テストやコメントで見つかったバグと退行を直す
• 追加のコメントに応えて、求められた変更を繰り返し直す

セットアップ#

クイックセットアップ#

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

1. マスクした CI/CD 変数を足す：「Settings」→「CI/CD」→「Variables」で、ANTHROPIC_API_KEY を足す（マスクし、必要なら protected にする）
2. .gitlab-ci.yml に Claude のジョブを足す

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  # Adjust rules to fit how you want to trigger the job:
  # - manual runs
  # - merge request events
  # - web/API triggers when a comment contains '@claude'
  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
    # The installer places claude in ~/.local/bin, which isn't on PATH in this image
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    # Optional: start a GitLab MCP server if your setup provides one
    - /bin/gitlab-mcp-server || true
    # Use AI_FLOW_* variables when invoking via web/API triggers with context payloads
    - 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

ジョブと ANTHROPIC_API_KEY 変数を足したら、「CI/CD」→「Pipelines」からジョブを手動で動かして試すか、MR から起動して、Claude にブランチで更新を提案させ、必要なら MR を開かせます。

手動セットアップ（本番向けに推奨）#

より制御のきいた設定にしたいとき、またはエンタープライズのプロバイダーが要るときの手順です。

1. プロバイダーのアクセスを設定する
   • Claude API：ANTHROPIC_API_KEY を作り、マスクした CI/CD 変数として保存する
   • Amazon Bedrock：GitLab の AWS OIDC を設定し、Amazon Bedrock 用の IAM ロールを作る
   • Google Cloud の Agent Platform：GitLab 用の Workload Identity Federation を GCP に設定する
2. GitLab API の操作のためのプロジェクトの資格情報を足す：既定では CI_JOB_TOKEN を使うか、api スコープのプロジェクトアクセストークンを作る。PAT を使うなら、GITLAB_ACCESS_TOKEN（マスク）として保存する
3. .gitlab-ci.yml に Claude のジョブを足す：Claude API には上のクイックセットアップのジョブを、プロバイダーには、下の「設定例」のジョブを使う
4. （任意）言及で起動するトリガーを有効にする：イベントのリスナーを使うなら、リスナーへ「Comments (notes)」のプロジェクト Webhook を足す。コメントが @claude を含むとき、リスナーが AI_FLOW_INPUT や AI_FLOW_CONTEXT のような変数つきでパイプラインのトリガー API を呼ぶようにする

使用例#

イシューを MR にする#

イシューのコメントで次のように書きます。Claude はイシューとコードベースを分析し、ブランチに変更を書き、レビュー用の MR を開きます。

@claude implement this feature based on the issue description

実装の助けを得る#

MR のディスカッションで書きます。Claude は変更を提案し、適切なキャッシュを持つコードを足して、MR を更新します。

@claude suggest a concrete approach to cache the results of this API call

バグを素早く直す#

イシューか MR のコメントで書きます。Claude はバグを見つけ、修正を実装し、ブランチを更新するか、新しい MR を開きます。

@claude fix the TypeError in the user dashboard component

Amazon Bedrock と Google Cloud で使う#

エンタープライズの環境では、同じ開発者体験のまま、Claude Code をすべて自分のクラウドのインフラで動かせます。

Amazon Bedrock#

前提：

1. 対象の Claude モデルに Amazon Bedrock のアクセスがある AWS アカウント
2. AWS IAM で、GitLab が OIDC のアイデンティティプロバイダーとして設定されている
3. Amazon Bedrock の権限を持ち、信頼ポリシーが GitLab のプロジェクトと ref に限られた IAM ロール
4. ロールの引き受けのための GitLab CI/CD 変数：AWS_ROLE_TO_ASSUME（ロールの ARN）、AWS_REGION（Amazon Bedrock のリージョン）

AWS で、GitLab の CI ジョブが OIDC で IAM ロールを引き受けられるように設定します（静的なキーなし）。

1. Amazon Bedrock を有効にし、対象の Claude モデルへのアクセスを申請する
2. まだなければ、GitLab 用の IAM OIDC プロバイダーを作る
3. GitLab の OIDC プロバイダーが信頼する IAM ロールを作り、自分のプロジェクトと protected な ref に限る
4. Amazon Bedrock の呼び出し API の、最小権限の許可を付ける

実行時にジョブの OIDC トークンを一時的な AWS の資格情報と交換するには、下の Amazon Bedrock のジョブ例を使います。

Google Cloud の Agent Platform#

前提：

1. 次を備えた Google Cloud のプロジェクト：Agent Platform API が有効、GitLab の OIDC を信頼する Workload Identity Federation が設定済み
2. 必要な Agent Platform の役割だけを持つ専用のサービスアカウント
3. GitLab の CI/CD 変数：GCP_WORKLOAD_IDENTITY_PROVIDER（//iam.googleapis.com/ の接頭辞を除いたプロバイダーのリソース名。例：projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider）、GCP_SERVICE_ACCOUNT（サービスアカウントのメールアドレス）、GCP_PROJECT_ID（Google Cloud のプロジェクト ID）

Google Cloud で、GitLab の CI ジョブが Workload Identity Federation でサービスアカウントになりすませるように設定します。

1. IAM Credentials API・STS API・Agent Platform API を有効にする
2. GitLab の OIDC 用の Workload Identity Pool とプロバイダーを作る
3. Agent Platform の役割を持つ専用のサービスアカウントを作る
4. WIF のプリンシパルに、サービスアカウントへのなりすましの権限を与える

キーを保存せずに認証するには、下の Agent Platform のジョブ例を使います。

設定例#

自分のパイプラインに合わせて直せる、すぐ使える断片です。

Amazon Bedrock のジョブ例（OIDC）#

前提：Amazon Bedrock が有効で、選んだ Claude モデルへのアクセスがある。AWS で GitLab の OIDC が設定され、自分の GitLab のプロジェクトと ref を信頼するロールがある。Amazon Bedrock の権限を持つ IAM ロール（最小権限を推奨）。

GitLab は、id_tokens: ブロックからジョブの OIDC トークンを発行し、GITLAB_OIDC_TOKEN として公開します。aud には、AWS の IAM OIDC のアイデンティティプロバイダーに設定した、オーディエンスの値（たとえば GitLab のインスタンスの URL）を設定します。

stages:
  - ai

claude-bedrock:
  stage: ai
  image: node:24-alpine3.21
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  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
    # The installer places claude in ~/.local/bin, which isn't on PATH in this image
    - export PATH="$HOME/.local/bin:$PATH"
    # Exchange the job's OIDC token for AWS credentials
    - 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
    - export AWS_ACCESS_KEY_ID="$(jq -r .Credentials.AccessKeyId /tmp/aws_creds.json)"
    - export AWS_SECRET_ACCESS_KEY="$(jq -r .Credentials.SecretAccessKey /tmp/aws_creds.json)"
    - export AWS_SESSION_TOKEN="$(jq -r .Credentials.SessionToken /tmp/aws_creds.json)"
  script:
    - /bin/gitlab-mcp-server || true
    - >
      claude
      -p "${AI_FLOW_INPUT:-'Implement the requested changes and open an MR'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write mcp__gitlab"
      --debug
  variables:
    AWS_REGION: "us-west-2"
    CLAUDE_CODE_USE_BEDROCK: "1"

Agent Platform のジョブ例（Workload Identity Federation）#

前提：GCP のプロジェクトで Agent Platform API が有効。GitLab の OIDC を信頼する Workload Identity Federation が設定済み。Agent Platform の権限を持つサービスアカウントがある。

GitLab は、id_tokens: ブロックからジョブの OIDC トークンを発行し、GITLAB_OIDC_TOKEN として公開します。aud には、Workload Identity Pool のプロバイダーに設定したオーディエンスの値（たとえば GitLab のインスタンスの URL）を設定します。ジョブはトークンをファイルへ書き、資格情報の設定の credential_source の項目が、Google の認証ライブラリに、そこから読むよう伝えます。GOOGLE_APPLICATION_CREDENTIALS を資格情報の設定ファイルに向けると、アプリケーションのデフォルトの資格情報（Application Default Credentials）を通して、Claude Code が使えます。

stages:
  - ai

claude-vertex:
  stage: ai
  image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.example.com
  before_script:
    - apt-get update && apt-get install -y git && apt-get clean
    - curl -fsSL https://claude.ai/install.sh | bash
    # The installer places claude in ~/.local/bin, which isn't on PATH in this image
    - export PATH="$HOME/.local/bin:$PATH"
    # Write the job's OIDC token where credential_source expects it
    - printf "%s" "$GITLAB_OIDC_TOKEN" > /tmp/oidc_token
    # Write the WIF credential configuration to a file (no downloaded keys)
    - |
      cat > /tmp/cred.json <<EOF
      {
        "type": "external_account",
        "audience": "//iam.googleapis.com/${GCP_WORKLOAD_IDENTITY_PROVIDER}",
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "token_url": "https://sts.googleapis.com/v1/token",
        "credential_source": {
          "file": "/tmp/oidc_token"
        },
        "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${GCP_SERVICE_ACCOUNT}:generateAccessToken"
      }
      EOF
    # Expose the credentials to Claude Code via Application Default Credentials
    - export GOOGLE_APPLICATION_CREDENTIALS=/tmp/cred.json
    # Authenticate the gcloud CLI with the same credential configuration
    - gcloud auth login --cred-file=/tmp/cred.json
    - gcloud config set project "$GCP_PROJECT_ID"
  script:
    - /bin/gitlab-mcp-server || true
    - >
      CLOUD_ML_REGION="${CLOUD_ML_REGION:-us-east5}"
      claude
      -p "${AI_FLOW_INPUT:-'Review and update code as requested'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write mcp__gitlab"
      --debug
  variables:
    CLOUD_ML_REGION: "us-east5"
    CLAUDE_CODE_USE_VERTEX: "1"
    ANTHROPIC_VERTEX_PROJECT_ID: "$GCP_PROJECT_ID"

ベストプラクティス#

• CLAUDE.md の設定：リポジトリのルートに CLAUDE.md を作り、コーディングの標準・レビューの基準・プロジェクト固有の規則を定義する。Claude は実行中にこのファイルを読み、変更を提案するとき、その慣例に従う（CLAUDE.md とメモリ）
• 性能：CLAUDE.md を絞って簡潔に保つ。イシューや MR の説明を明確にして、反復を減らす。ランナーで、npm とパッケージのインストールをできるかぎりキャッシュする

セキュリティ#

• ANTHROPIC_API_KEY を、マスクした変数として足す（必要なら protected にする）
• 可能な限り、プロバイダー固有の OIDC を使う（長期のキーなし）
• ジョブの権限とネットワークの外向きの通信を制限する
• Claude の MR を、ほかのコントリビューターの MR と同じようにレビューする

CI のコスト#

GitLab CI/CD で Claude Code を使うときは、次のコストに気をつけます。

• GitLab ランナーの時間：Claude は自分の GitLab ランナーで動き、計算時間の分を消費する。詳しくは GitLab のプランのランナーの課金を見る
• API のコスト：各やり取りが、プロンプトと応答の大きさに応じてトークンを消費する。使用量は、作業の複雑さとコードベースの大きさで変わる。詳しくは Anthropic の料金を見る
• コストを抑えるコツ：具体的な @claude のコマンドを使って、無駄なターンを減らす。適切な --max-turns とジョブの timeout の値を設定する。並列の実行を制限するため、同時実行を制限する

全体のコストの考え方はコストを抑えるを見てください。

トラブルシューティング#

詳細な設定#

よく使うパラメーターと変数#

ジョブの中の Claude Code の実行は、次の CLI のフラグ・GitLab のキーワード・変数で制御します。

Claude の動作を調整する#

Claude を導く主な方法は2つあります。

1. CLAUDE.md：コーディングの標準・セキュリティの要件・プロジェクトの慣例を定義する。Claude は実行中にこれを読み、規則に従う
2. カスタムのプロンプト：ジョブの -p で、作業固有の指示を渡す。ジョブごとに別のプロンプトを使える（例：レビュー・実装・リファクタリング）

GitHub を使うリポジトリでは、GitHub Actions を見てください。