GitLab CI/CD用のClaude Codeは現在ベータ版です。エクスペリエンスを改善する過程で、機能や動作が変更される可能性があります。この統合はGitLabによって維持されています。サポートについては、以下のGitLabイシューをご覧ください。
この統合はClaude Code CLIとSDKの上に構築されており、CI/CDジョブとカスタム自動化ワークフローでClaudeをプログラム的に使用できます。
なぜGitLabでClaude Codeを使用するのか?
- 即座のMR作成: 必要なことを説明すると、Claudeが変更と説明を含む完全なMRを提案します
- 自動実装: 単一のコマンドまたはメンションでイシューを動作するコードに変換します
- プロジェクト認識: Claudeはあなたの
CLAUDE.mdガイドラインと既存のコードパターンに従います - 簡単なセットアップ:
.gitlab-ci.ymlに1つのジョブとマスクされたCI/CD変数を追加するだけです - エンタープライズ対応: Claude API、AWS Bedrock、またはGoogle Vertex AIを選択して、データ居住性と調達要件を満たします
- デフォルトで安全: ブランチ保護と承認を使用してGitLabランナーで実行されます
仕組み
Claude CodeはGitLab CI/CDを使用して、分離されたジョブでAIタスクを実行し、MRを介して結果をコミットバックします:-
イベント駆動オーケストレーション: GitLabは選択したトリガー(例:イシュー、MR、またはレビュースレッドで
@claudeをメンションするコメント)をリッスンします。ジョブはスレッドとリポジトリからコンテキストを収集し、その入力からプロンプトを構築し、Claude Codeを実行します。 -
プロバイダー抽象化: 環境に適したプロバイダーを使用します:
- Claude API(SaaS)
- AWS Bedrock(IAMベースのアクセス、クロスリージョンオプション)
- Google Vertex AI(GCPネイティブ、Workload Identity Federation)
- サンドボックス実行: 各インタラクションは、厳格なネットワークとファイルシステムルールを持つコンテナで実行されます。Claude Codeはワークスペーススコープの権限を強制して書き込みを制約します。すべての変更はMRを通じて流れるため、レビュアーは差分を確認でき、承認も引き続き適用されます。
Claudeができること
Claude Codeは、コードとの作業方法を変革する強力なCI/CDワークフローを可能にします:- イシューの説明やコメントからMRを作成・更新する
- パフォーマンス回帰を分析し、最適化を提案する
- ブランチで直接機能を実装し、MRを開く
- テストやコメントで特定されたバグや回帰を修正する
- フォローアップコメントに応答して、要求された変更を反復する
セットアップ
クイックセットアップ
最も速い開始方法は、.gitlab-ci.ymlに最小限のジョブを追加し、APIキーをマスクされた変数として設定することです。
-
マスクされたCI/CD変数を追加
- 設定 → CI/CD → 変数に移動
ANTHROPIC_API_KEYを追加(マスク、必要に応じて保護)
-
.gitlab-ci.ymlにClaudeジョブを追加
ANTHROPIC_API_KEY変数を追加した後、CI/CD → パイプラインからジョブを手動で実行してテストするか、MRからトリガーしてClaudeがブランチで更新を提案し、必要に応じてMRを開くようにします。
Claude APIの代わりにAWS BedrockまたはGoogle Vertex AIで実行するには、認証と環境設定について以下のAWS Bedrock & Google Vertex AIでの使用セクションをご覧ください。
手動セットアップ(本番環境推奨)
より制御されたセットアップまたはエンタープライズプロバイダーが必要な場合:-
プロバイダーアクセスを設定:
- Claude API:
ANTHROPIC_API_KEYをマスクされたCI/CD変数として作成・保存 - AWS Bedrock: GitLab → AWS OIDCを設定し、Bedrock用のIAMロールを作成
- Google Vertex AI: GitLab → GCP用のWorkload Identity Federationを設定
- Claude API:
-
GitLab API操作用のプロジェクト認証情報を追加:
- デフォルトで
CI_JOB_TOKENを使用するか、apiスコープでProject Access Tokenを作成 - PATを使用する場合は
GITLAB_ACCESS_TOKEN(マスク)として保存
- デフォルトで
-
.gitlab-ci.ymlにClaudeジョブを追加(以下の例を参照) -
(オプション)メンション駆動トリガーを有効化:
- イベントリスナー(使用している場合)に「コメント(ノート)」用のプロジェクトWebhookを追加
- コメントに
@claudeが含まれる場合、AI_FLOW_INPUTやAI_FLOW_CONTEXTなどの変数でパイプライントリガーAPIを呼び出すようにリスナーを設定
使用例
イシューをMRに変換
イシューコメントで:実装のヘルプを得る
MRディスカッションで:バグを迅速に修正
イシューまたはMRコメントで:AWS Bedrock & Google Vertex AIでの使用
エンタープライズ環境では、同じ開発者エクスペリエンスで、Claude Codeを完全にクラウドインフラストラクチャ上で実行できます。前提条件
AWS BedrockでClaude Codeを設定する前に、以下が必要です:- 希望するClaudeモデルへのAmazon Bedrockアクセスを持つAWSアカウント
- AWS IAMでOIDCアイデンティティプロバイダーとして設定されたGitLab
- Bedrock権限とGitLabプロジェクト/refsに制限された信頼ポリシーを持つIAMロール
- ロール引き受け用のGitLab CI/CD変数:
AWS_ROLE_TO_ASSUME(ロールARN)AWS_REGION(Bedrockリージョン)
セットアップ手順
OIDC経由でGitLab CIジョブがIAMロールを引き受けられるようにAWSを設定します(静的キーなし)。必要なセットアップ:- Amazon Bedrockを有効化し、対象のClaudeモデルへのアクセスを要求
- まだ存在しない場合、GitLab用のIAM OIDCプロバイダーを作成
- GitLab OIDCプロバイダーに信頼され、プロジェクトと保護されたrefsに制限されたIAMロールを作成
- Bedrock呼び出しAPI用の最小権限を付与
AWS_ROLE_TO_ASSUMEAWS_REGION
設定例
以下は、パイプラインに適応できるすぐに使用可能なスニペットです。基本的な.gitlab-ci.yml(Claude API)
AWS Bedrockジョブ例(OIDC)
前提条件:- 選択したClaudeモデルへのアクセスを持つAmazon Bedrockが有効
- GitLabプロジェクトとrefsを信頼するロールでAWSに設定されたGitLab OIDC
- Bedrock権限を持つIAMロール(最小権限推奨)
AWS_ROLE_TO_ASSUME: Bedrockアクセス用のIAMロールのARNAWS_REGION: Bedrockリージョン(例:us-west-2)
BedrockのモデルIDには、リージョン固有のプレフィックスとバージョンサフィックスが含まれます(例:
us.anthropic.claude-3-7-sonnet-20250219-v1:0)。ワークフローがサポートしている場合、ジョブ設定またはプロンプト経由で希望するモデルを渡してください。Google Vertex AIジョブ例(Workload Identity Federation)
前提条件:- GCPプロジェクトでVertex AI APIが有効
- GitLab OIDCを信頼するように設定されたWorkload Identity Federation
- Vertex AI権限を持つサービスアカウント
GCP_WORKLOAD_IDENTITY_PROVIDER: 完全なプロバイダーリソース名GCP_SERVICE_ACCOUNT: サービスアカウントメールCLOUD_ML_REGION: Vertexリージョン(例:us-east5)
Workload Identity Federationでは、サービスアカウントキーを保存する必要がありません。リポジトリ固有の信頼条件と最小権限サービスアカウントを使用してください。
ベストプラクティス
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_*変数を介して十分なコンテキストを持っていることを確認
認証エラー
- Claude API用:
ANTHROPIC_API_KEYが有効で期限切れでないことを確認 - Bedrock/Vertex用: OIDC/WIF設定、ロール偽装、シークレット名を確認;リージョンとモデルの可用性を確認
高度な設定
一般的なパラメータと変数
Claude Codeは、これらの一般的に使用される入力をサポートします:prompt/prompt_file: インライン(-p)またはファイル経由で指示を提供max_turns: やり取りの反復回数を制限timeout_minutes: 総実行時間を制限ANTHROPIC_API_KEY: Claude APIに必要(Bedrock/Vertexでは使用されません)- プロバイダー固有の環境:
AWS_REGION、Vertex用のプロジェクト/リージョン変数
正確なフラグとパラメータは
@anthropic-ai/claude-codeのバージョンによって異なる場合があります。サポートされているオプションを確認するには、ジョブでclaude --helpを実行してください。Claudeの動作をカスタマイズ
Claudeを主に2つの方法でガイドできます:- CLAUDE.md: コーディング標準、セキュリティ要件、プロジェクト規約を定義します。Claudeは実行中にこれを読み取り、あなたのルールに従います。
- カスタムプロンプト: ジョブで
prompt/prompt_fileを介してタスク固有の指示を渡します。異なるジョブに異なるプロンプトを使用します(例:レビュー、実装、リファクタリング)。