Claude Code for GitLab CI/CD は現在ベータ版です。機能と機能性は、エクスペリエンスを改善する際に進化する可能性があります。この統合は GitLab によって保守されています。サポートについては、以下の GitLab issue を参照してください。
この統合は 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 は選択したトリガー(たとえば、issue、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 ワークフローを実現します:- issue の説明またはコメントから MR を作成および更新します
- パフォーマンス低下を分析し、最適化を提案します
- ブランチに直接機能を実装し、MR を開きます
- テストまたはコメントで特定されたバグと低下を修正します
- フォローアップコメントに応答して、リクエストされた変更を反復処理します
セットアップ
クイックセットアップ
最速で始める方法は、.gitlab-ci.yml に最小限のジョブを追加し、API キーをマスクされた変数として設定することです。
-
マスクされた CI/CD 変数を追加します
- Settings → CI/CD → Variables に移動します
ANTHROPIC_API_KEYを追加します(マスク、必要に応じて保護)
-
Claude ジョブを
.gitlab-ci.ymlに追加します
ANTHROPIC_API_KEY 変数を追加した後、CI/CD → Pipelines からジョブを手動で実行してテストするか、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 用 Workload Identity Federation を構成 → GCP
- Claude API:
-
GitLab API 操作用のプロジェクト認証情報を追加します:
- デフォルトで
CI_JOB_TOKENを使用するか、apiスコープを持つプロジェクトアクセストークンを作成します - PAT を使用する場合は
GITLAB_ACCESS_TOKEN(マスク)として保存します
- デフォルトで
-
Claude ジョブを
.gitlab-ci.ymlに追加します(以下の例を参照) -
(オプション)メンション駆動型トリガーを有効にします:
- 「Comments (notes)」のプロジェクト webhook をイベントリスナーに追加します(使用する場合)
- コメントに
@claudeが含まれている場合、リスナーがパイプライントリガー API をAI_FLOW_INPUTやAI_FLOW_CONTEXTなどの変数で呼び出すようにします
使用例
issue を MR に変換する
issue コメント内:実装ヘルプを取得する
MR ディスカッション内:バグをすばやく修正する
issue または MR コメント内:AWS Bedrock & Google Vertex AI での使用
エンタープライズ環境では、同じ開発者エクスペリエンスで Claude Code をクラウドインフラストラクチャ全体で実行できます。- AWS Bedrock
- Google Vertex AI
前提条件
AWS Bedrock で Claude Code をセットアップする前に、以下が必要です:- 目的の Claude モデルへの Amazon Bedrock アクセスを持つ AWS アカウント
- AWS IAM で OIDC ID プロバイダーとして構成された GitLab
- Bedrock 権限と GitLab プロジェクト/refs に制限されたトラストポリシーを持つ IAM ロール
- ロール仮定用の GitLab CI/CD 変数:
AWS_ROLE_TO_ASSUME(ロール ARN)AWS_REGION(Bedrock リージョン)
セットアップ手順
GitLab CI ジョブが OIDC 経由で IAM ロールを仮定できるように AWS を構成します(静的キーなし)。必須セットアップ:- Amazon Bedrock を有効にし、ターゲット Claude モデルへのアクセスをリクエストします
- まだ存在しない場合は GitLab 用の IAM OIDC プロバイダーを作成します
- GitLab OIDC プロバイダーによって信頼され、プロジェクトと保護された refs に制限された IAM ロールを作成します
- Bedrock invoke API の最小権限権限を付与します
AWS_ROLE_TO_ASSUMEAWS_REGION
構成例
以下は、パイプラインに適応できる準備完了のスニペットです。基本的な .gitlab-ci.yml (Claude API)
AWS Bedrock ジョブの例 (OIDC)
前提条件:- Amazon Bedrock が有効で、選択した Claude モデルへのアクセスがある
- GitLab OIDC が AWS で構成され、GitLab プロジェクトと refs を信頼するロールがある
- Bedrock 権限を持つ IAM ロール(最小権限を推奨)
AWS_ROLE_TO_ASSUME: Bedrock アクセス用の IAM ロールの ARNAWS_REGION: Bedrock リージョン(例:us-west-2)
Bedrock のモデル ID には、リージョン固有のプレフィックスとバージョンサフィックスが含まれます(例:
us.anthropic.claude-sonnet-4-5-20250929-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を焦点を絞った簡潔なものに保ちます- 明確な issue/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スコープを持つプロジェクトアクセストークンを使用しますmcp__gitlabツールが--allowedToolsで有効になっていることを確認します- ジョブが 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経由でタスク固有の指示を渡します。異なるジョブに異なるプロンプトを使用します(例: レビュー、実装、リファクタリング)。