Claude Code GitLab CI/CD

​

GitLabでClaude Codeを使用する理由

• 即座のMR作成: 必要なことを説明すると、Claudeが変更と説明を含む完全なMRを提案します
• 自動実装: 単一のコマンドやメンションでイシューを動作するコードに変換します
• プロジェクト対応: ClaudeはCLAUDE.mdガイドラインと既存のコードパターンに従います
• 簡単なセットアップ: .gitlab-ci.ymlに1つのジョブとマスクされたCI/CD変数を追加するだけです
• エンタープライズ対応: データ常駐と調達要件を満たすために、Anthropic API、AWS Bedrock、またはGoogle Vertex AIを選択できます
• デフォルトで安全: ブランチ保護と承認を含むGitLabランナーで実行されます

​

動作原理

Claude CodeはGitLab CI/CDを使用してAIタスクを分離されたジョブで実行し、MRを通じて結果をコミットバックします：

1. イベント駆動オーケストレーション: GitLabは選択したトリガー（例：イシュー、MR、またはレビュースレッドで@claudeをメンションするコメント）をリッスンします。ジョブはスレッドとリポジトリからコンテキストを収集し、その入力からプロンプトを構築し、Claude Codeを実行します。

2. プロバイダー抽象化: 環境に適したプロバイダーを使用します：

   • Anthropic API（SaaS）
   • AWS Bedrock（IAMベースアクセス、クロスリージョンオプション）
   • Google Vertex AI（GCPネイティブ、Workload Identity Federation）

3. サンドボックス実行: 各インタラクションは厳格なネットワークとファイルシステムルールを持つコンテナで実行されます。Claude Codeはワークスペーススコープの権限を強制して書き込みを制約します。すべての変更はMRを通じて流れるため、レビュアーは差分を確認でき、承認も引き続き適用されます。

レイテンシを削減し、データ主権要件を満たしながら、既存のクラウド契約を使用するために地域エンドポイントを選択します。

​

Claudeができること

Claude Codeは、コードとの作業方法を変革する強力なCI/CDワークフローを可能にします：

• イシューの説明やコメントからMRを作成・更新
• パフォーマンス回帰を分析し、最適化を提案
• ブランチで直接機能を実装し、MRを開く
• テストやコメントで特定されたバグや回帰を修正
• フォローアップコメントに応答して、要求された変更を反復

​

セットアップ

​

クイックセットアップ

開始する最も速い方法は、.gitlab-ci.ymlに最小限のジョブを追加し、APIキーをマスクされた変数として設定することです。

1. マスクされたCI/CD変数を追加

   • 設定 → CI/CD → 変数に移動
   • ANTHROPIC_API_KEYを追加（マスク、必要に応じて保護）

2. .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
    - npm install -g @anthropic-ai/claude-code
  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:-'このMRをレビューし、要求された変更を実装してください'}"
      --permission-mode acceptEdits
      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
      --debug

ジョブとANTHROPIC_API_KEY変数を追加した後、CI/CD → パイプラインからジョブを手動で実行してテストするか、MRからトリガーしてClaudeにブランチで更新を提案させ、必要に応じてMRを開かせます。

​

手動セットアップ（本番環境推奨）

より制御されたセットアップを希望する場合、またはエンタープライズプロバイダーが必要な場合：

1. プロバイダーアクセスを設定：

   • Anthropic API: ANTHROPIC_API_KEYをマスクされたCI/CD変数として作成・保存
   • AWS Bedrock: GitLab → AWS OIDCを設定し、Bedrock用のIAMロールを作成
   • Google Vertex AI: GitLab → GCP用のWorkload Identity Federationを設定

2. GitLab API操作用のプロジェクト認証情報を追加：

   • デフォルトでCI_JOB_TOKENを使用するか、apiスコープでProject Access Tokenを作成
   • PATを使用する場合はGITLAB_ACCESS_TOKEN（マスク）として保存

3. .gitlab-ci.ymlにClaudeジョブを追加（以下の例を参照）

4. （オプション）メンション駆動トリガーを有効化：

   • イベントリスナー（使用する場合）に「コメント（ノート）」用のプロジェクトWebhookを追加
   • コメントに@claudeが含まれる場合、リスナーにAI_FLOW_INPUTやAI_FLOW_CONTEXTなどの変数でパイプライントリガーAPIを呼び出させる

​

使用例

​

イシューをMRに変換

イシューコメントで：

@claude イシューの説明に基づいてこの機能を実装してください

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

​

実装ヘルプを取得

MRディスカッションで：

@claude このAPI呼び出しの結果をキャッシュする具体的なアプローチを提案してください

Claudeは変更を提案し、適切なキャッシュでコードを追加し、MRを更新します。

​

バグを迅速に修正

イシューまたはMRコメントで：

@claude ユーザーダッシュボードコンポーネントのTypeErrorを修正してください

Claudeはバグを特定し、修正を実装し、ブランチを更新するか新しいMRを開きます。

​

AWS Bedrock & Google Vertex AIでの使用

エンタープライズ環境では、同じ開発者エクスペリエンスで、Claude Codeを完全にクラウドインフラストラクチャ上で実行できます。

# AWS Bedrock用：
- AWS_ROLE_TO_ASSUME
- AWS_REGION

# AWS Bedrock用：
- AWS_ROLE_TO_ASSUME
- AWS_REGION

# Google Vertex AI用：
- GCP_WORKLOAD_IDENTITY_PROVIDER
- GCP_SERVICE_ACCOUNT
- CLOUD_ML_REGION（例：us-east5）

​

設定例

以下は、パイプラインに適応できる使用準備完了のスニペットです。

​

基本的な.gitlab-ci.yml（Anthropic API）

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
    - npm install -g @anthropic-ai/claude-code
  script:
    - /bin/gitlab-mcp-server || true
    - >
      claude
      -p "${AI_FLOW_INPUT:-'最近の変更を要約し、改善を提案してください'}"
      --permission-mode acceptEdits
      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
      --debug
  # Claude CodeはCI/CD変数からANTHROPIC_API_KEYを使用します

​

AWS Bedrockジョブ例（OIDC）

前提条件：

• 選択したClaudeモデルへのアクセスを持つAmazon Bedrockが有効
• GitLabプロジェクトとrefsを信頼するロールでAWSに設定されたGitLab OIDC
• Bedrock権限を持つIAMロール（最小権限推奨）

必要なCI/CD変数：

• AWS_ROLE_TO_ASSUME: Bedrockアクセス用のIAMロールのARN
• AWS_REGION: Bedrockリージョン（例：us-west-2）

claude-bedrock:
  stage: ai
  image: node:24-alpine3.21
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  before_script:
    - apk add --no-cache bash curl jq git python3 py3-pip
    - pip install --no-cache-dir awscli
    - npm install -g @anthropic-ai/claude-code
    # GitLab OIDCトークンをAWS認証情報と交換
    - export AWS_WEB_IDENTITY_TOKEN_FILE="${CI_JOB_JWT_FILE:-/tmp/oidc_token}"
    - if [ -n "${CI_JOB_JWT_V2}" ]; then printf "%s" "$CI_JOB_JWT_V2" > "$AWS_WEB_IDENTITY_TOKEN_FILE"; fi
    - >
      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:-'要求された変更を実装してMRを開いてください'}"
      --permission-mode acceptEdits
      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
      --debug
  variables:
    AWS_REGION: "us-west-2"

​

Google Vertex AIジョブ例（Workload Identity Federation）

前提条件：

• GCPプロジェクトでVertex AI APIが有効
• GitLab OIDCを信頼するように設定されたWorkload Identity Federation
• Vertex AI権限を持つサービスアカウント

必要なCI/CD変数：

• GCP_WORKLOAD_IDENTITY_PROVIDER: 完全なプロバイダーリソース名
• GCP_SERVICE_ACCOUNT: サービスアカウントメール
• CLOUD_ML_REGION: Vertexリージョン（例：us-east5）

claude-vertex:
  stage: ai
  image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  before_script:
    - apt-get update && apt-get install -y git nodejs npm && apt-get clean
    - npm install -g @anthropic-ai/claude-code
    # WIF経由でGoogle Cloudに認証（ダウンロードされたキーなし）
    - >
      gcloud auth login --cred-file=<(cat <<EOF
      {
        "type": "external_account",
        "audience": "${GCP_WORKLOAD_IDENTITY_PROVIDER}",
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${GCP_SERVICE_ACCOUNT}:generateAccessToken",
        "token_url": "https://sts.googleapis.com/v1/token"
      }
      EOF
      )
    - gcloud config set project "$(gcloud projects list --format='value(projectId)' --filter="name:${CI_PROJECT_NAMESPACE}" | head -n1)" || true
  script:
    - /bin/gitlab-mcp-server || true
    - >
      CLOUD_ML_REGION="${CLOUD_ML_REGION:-us-east5}"
      claude
      -p "${AI_FLOW_INPUT:-'要求に応じてコードをレビューし更新してください'}"
      --permission-mode acceptEdits
      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
      --debug
  variables:
    CLOUD_ML_REGION: "us-east5"

​

ベストプラクティス

​

CLAUDE.md設定

リポジトリルートにCLAUDE.mdファイルを作成して、コーディング標準、レビュー基準、プロジェクト固有のルールを定義します。Claudeは実行中にこのファイルを読み取り、変更を提案する際に規約に従います。

​

セキュリティ考慮事項

APIキーやクラウド認証情報をリポジトリにコミットしないでください！常にGitLab CI/CD変数を使用してください：

• ANTHROPIC_API_KEYをマスクされた変数として追加（必要に応じて保護）
• 可能な場合はプロバイダー固有のOIDCを使用（長期間有効なキーなし）
• ジョブ権限とネットワーク出力を制限
• 他の貢献者と同様にClaudeのMRをレビュー

​

パフォーマンス最適化

• CLAUDE.mdを焦点を絞って簡潔に保つ
• 反復を減らすために明確なイシュー/MR説明を提供
• 暴走実行を避けるために適切なジョブタイムアウトを設定
• 可能な場合、ランナーでnpmとパッケージインストールをキャッシュ

​

CIコスト

GitLab CI/CDでClaude Codeを使用する際は、関連コストに注意してください：

• GitLabランナー時間：

  • ClaudeはGitLabランナーで実行され、計算分を消費します
  • 詳細については、GitLabプランのランナー課金をご覧ください

• APIコスト：

  • 各Claudeインタラクションは、プロンプトと応答サイズに基づいてトークンを消費します
  • トークン使用量は、タスクの複雑さとコードベースサイズによって異なります
  • 詳細についてはAnthropic価格をご覧ください

• コスト最適化のヒント：

  • 不要なターンを減らすために具体的な@claudeコマンドを使用
  • 適切なmax_turnsとジョブタイムアウト値を設定
  • 並列実行を制御するために同時実行を制限

​

セキュリティとガバナンス

• 各ジョブは制限されたネットワークアクセスを持つ分離されたコンテナで実行されます
• Claudeの変更はMRを通じて流れるため、レビュアーはすべての差分を確認できます
• ブランチ保護と承認ルールがAI生成コードに適用されます
• Claude Codeはワークスペーススコープの権限を使用して書き込みを制約します
• 独自のプロバイダー認証情報を持参するため、コストは制御下に留まります

​

トラブルシューティング

​

Claudeが@claudeコマンドに応答しない

• パイプラインがトリガーされていることを確認（手動、MRイベント、またはノートイベントリスナー/Webhook経由）
• CI/CD変数（ANTHROPIC_API_KEYまたはクラウドプロバイダー設定）が存在し、マスクされていないことを確認
• コメントに@claude（/claudeではない）が含まれ、メンショントリガーが設定されていることを確認

​

ジョブがコメントを書き込めない、またはMRを開けない

• CI_JOB_TOKENがプロジェクトに十分な権限を持っていることを確認するか、apiスコープでProject Access Tokenを使用
• --allowedToolsでmcp__gitlabツールが有効になっていることを確認
• ジョブがMRのコンテキストで実行されるか、AI_FLOW_*変数を通じて十分なコンテキストを持っていることを確認

​

認証エラー

• Anthropic API用: ANTHROPIC_API_KEYが有効で期限切れでないことを確認
• Bedrock/Vertex用: OIDC/WIF設定、ロール偽装、シークレット名を確認；リージョンとモデルの可用性を確認

​

高度な設定

​

一般的なパラメータと変数

Claude Codeは以下の一般的に使用される入力をサポートします：

• prompt / prompt_file: インライン（-p）またはファイル経由で指示を提供
• max_turns: やり取りの反復回数を制限
• timeout_minutes: 総実行時間を制限
• ANTHROPIC_API_KEY: Anthropic APIに必要（Bedrock/Vertexでは使用されません）
• プロバイダー固有の環境: AWS_REGION、Vertex用のプロジェクト/リージョン変数

​

Claudeの動作をカスタマイズ

Claudeを主に2つの方法でガイドできます：

1. CLAUDE.md: コーディング標準、セキュリティ要件、プロジェクト規約を定義します。Claudeは実行中にこれを読み取り、ルールに従います。
2. カスタムプロンプト: ジョブでprompt/prompt_fileを通じてタスク固有の指示を渡します。異なるジョブに異なるプロンプトを使用します（例：レビュー、実装、リファクタリング）。