SpyBara
Go Premium

gitlab-ci-cd.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 150 additions and 185 deletions.

2026
Wed 9 22:58

Claude Code GitLab CI/CD

Claude Code を GitLab CI/CD で開発ワークフローに統合する方法を学びます

GitLab で Claude Code を使用する理由

  • インスタント MR 作成: 必要なことを説明すると、Claude は変更と説明を含む完全な MR を提案します
  • 自動実装: 単一のコマンドまたはメンションで issue を実行可能なコードに変換します
  • プロジェクト対応: Claude は CLAUDE.md ガイドラインと既存のコードパターンに従います
  • シンプルなセットアップ: .gitlab-ci.yml に 1 つのジョブとマスクされた CI/CD 変数を追加します
  • エンタープライズ対応: Claude API、Amazon Bedrock、または Google Cloud の Agent Platform を選択して、データレジデンシーと調達のニーズを満たします
  • デフォルトでセキュア: GitLab ランナーで実行され、ブランチ保護と承認が適用されます

仕組み

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

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

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

    • Claude API（SaaS）
    • Amazon Bedrock（IAM ベースのアクセス、クロスリージョンオプション）
    • Google Cloud の Agent Platform（GCP ネイティブ、Workload Identity Federation）

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

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

Claude にはどのようなことができますか？

GitLab パイプラインでは、Claude Code は以下のことができます：

  • issue の説明またはコメントから MR を作成および更新する
  • パフォーマンス低下を分析し、最適化を提案する
  • ブランチに機能を直接実装してから MR を開く
  • テストまたはコメントで特定されたバグおよび低下を修正する
  • フォローアップコメントに応答して、リクエストされた変更を反復する

セットアップ

クイックセットアップ

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

  1. マスク CI/CD 変数を追加する

    • Settings → CI/CD → Variables に移動します
    • 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
    - 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

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

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

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

    • Claude API：ANTHROPIC_API_KEY を作成してマスク CI/CD 変数として保存します
    • Amazon Bedrock：Configure GitLab → AWS OIDC を設定し、Amazon Bedrock 用の IAM ロールを作成します
    • Google Cloud の Agent Platform：Configure Workload Identity Federation for GitLab → GCP を設定します

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

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

  3. .gitlab-ci.yml に Claude ジョブを追加する：Claude API の場合は クイックセットアップ ジョブを使用するか、設定例 からプロバイダージョブを使用します

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

    • 「Comments (notes)」のプロジェクト webhook をイベントリスナー（使用している場合）に追加します
    • コメントに @claude が含まれている場合、リスナーが AI_FLOW_INPUT や AI_FLOW_CONTEXT などの変数を使用してパイプライントリガー API を呼び出すようにします

使用例

Issue を MR に変換する

Issue コメント内：

@claude implement this feature based on the issue description

Claude は Issue とコードベースを分析し、ブランチで変更を記述して、レビュー用の MR を開きます。

実装サポートを取得する

MR ディスカッション内：

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

Claude は変更を提案し、適切なキャッシング機能を備えたコードを追加し、MR を更新します。

バグを素早く修正する

Issue または MR コメント内：

@claude fix the TypeError in the user dashboard component

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

Amazon Bedrock と Google Cloud での使用

エンタープライズ環境では、Claude Code をクラウドインフラストラクチャ全体で実行でき、同じ開発者体験を得られます。

前提条件

Amazon Bedrock で Claude Code をセットアップする前に、以下が必要です。

  1. 目的の Claude モデルへの Amazon Bedrock アクセス権を持つ AWS アカウント
  2. AWS IAM で OIDC アイデンティティプロバイダーとして設定された GitLab
  3. Amazon Bedrock 権限を持つ IAM ロールと、GitLab プロジェクト/refs に制限されたトラストポリシー
  4. ロール引き受けのための GitLab CI/CD 変数：
  • AWS_ROLE_TO_ASSUME（ロール ARN）
  • AWS_REGION（Amazon Bedrock リージョン）

セットアップ手順

GitLab CI ジョブが OIDC 経由で IAM ロールを引き受けることを許可するよう AWS を設定します（静的キーは不要）。

必須セットアップ：

  1. Amazon Bedrock を有効にし、目的の Claude モデルへのアクセスをリクエストします
  2. まだ存在しない場合は、GitLab 用の IAM OIDC プロバイダーを作成します
  3. GitLab OIDC プロバイダーによって信頼され、プロジェクトと保護された refs に制限された IAM ロールを作成します
  4. Amazon Bedrock invoke API に対する最小権限パーミッションをアタッチします

Amazon Bedrock ジョブの例を使用して、実行時にジョブの OIDC トークンを一時的な AWS 認証情報と交換します。

設定例

以下は、パイプラインに適応させることができる、すぐに使用できるスニペットです。

Amazon Bedrock ジョブの例（OIDC）

前提条件：

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

必須 CI/CD 変数：

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

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）

前提条件：

  • Google Cloud の Agent Platform API が GCP プロジェクトで有効化
  • Workload Identity Federation が GitLab OIDC を信頼するように設定
  • Google Cloud の Agent Platform 権限を持つサービスアカウント

必須 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
  • CLOUD_ML_REGION：Google Cloud の Agent Platform リージョン（例：us-east5）

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 はランの実行中にこのファイルを読み込み、変更を提案する際にあなたの規約に従います。

セキュリティに関する考慮事項

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

  • ANTHROPIC_API_KEY をマスク変数として追加します（必要に応じて保護してください）
  • 可能な限りプロバイダー固有の OIDC を使用します（長期的なキーは不要）
  • ジョブの権限とネットワーク出力を制限します
  • Claude の MR を他のコントリビューターと同じようにレビューします

パフォーマンスの最適化

  • CLAUDE.md を焦点を絞った簡潔なものに保ちます
  • 明確なイシュー/MR の説明を提供して、反復を減らします
  • ランナーで npm とパッケージのインストールをキャッシュします（可能な場合）

CI コスト

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

  • GitLab ランナー時間：

    • Claude はあなたの GitLab ランナーで実行され、コンピュート分を消費します
    • 詳細については、GitLab プランのランナー課金を参照してください

  • API コスト：

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

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

    • 特定の @claude コマンドを使用して、不要なターンを減らします
    • 適切な --max-turns とジョブ timeout 値を設定します
    • 並列実行を制御するために同時実行を制限します

トラブルシューティング

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

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

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

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

認証エラー

  • Claude API の場合: ANTHROPIC_API_KEY が有効で期限切れでないことを確認してください
  • Amazon Bedrock または Google Cloud の Agent Platform の場合: OIDC/WIF 設定、ロール偽装、シークレット名を確認してください。リージョンとモデルの可用性を確認してください

高度な設定

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

これらの CLI フラグ、GitLab キーワード、および変数を使用して、ジョブ内の Claude Code 実行を制御します。

  • -p: インラインで指示を提供します。例えば claude -p "Review this MR"
  • --max-turns: バックアンドフォース反復の回数を制限します
  • timeout: GitLab のジョブレベルの timeout キーワードで総ジョブ実行時間を制限します。例えば timeout: 30m
  • ANTHROPIC_API_KEY: Claude API に必要です（Amazon Bedrock または Google Cloud の Agent Platform では使用されません）
  • プロバイダー固有の環境: AWS_REGION、Google Cloud の Agent Platform のプロジェクト/リージョン変数

Claude の動作をカスタマイズする

Claude をガイドする方法は 2 つあります。

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