Claude Code GitLab CI/CD｜公式ジョブを1行ずつ読んで動かす

GitLab CI/CDでClaude Codeを動かす最小構成は、マスクしたCI/CD変数1つと、claude -p を呼ぶジョブ1つです。まずは公式ドキュメントのQuick setupに載っているジョブをそのまま掲げます。

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
    - curl -fsSL https://claude.ai/install.sh | bash
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    - /bin/gitlab-mcp-server || true
    - 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

公式の例にあるコメント行は省略して載せています。以降の節で、この各行の役割、変数の置き場所、手動実行で確認できる範囲、権限と上限の確かめ方、詰まったときの見る場所を順に整理します。MRはMerge Request（GitLabのマージリクエスト）の略です。

この記事の前提と未確認事項

公式ページ(英語版)によると、GitLab向けの連携はベータで、保守はGitLabが担当し、サポートはGitLabのissue(https://gitlab.com/gitlab-org/gitlab/-/issues/573776)が窓口です。機能は変わる可能性があります。

公式の記述の再構成であり、筆者が実機で測った結果は含みません。

公式ページに記載がなく、確認できていない点は次のとおりです。

対応するGitLabのバージョンとエディション(SaaS / セルフホスト)、プランによる制限

ページの公開日と更新日、日本語版との差異、日本語UIでの画面表示名

/bin/gitlab-mcp-server の入手元と提供形態

成功を示すログ文言や画面、エラー文言そのもの

MRの文脈も AI_FLOW_INPUT も無い手動実行での挙動(ブランチ更新やMR作成が起きるか)と、手動実行時の変数の渡し方

@claude コメントを受けるリスナーの実装方法と、webhook以外のコメント起動経路

acceptEdits とBash許可をCIに組み込むリスクの評価

具体的な料金額(公式は料金ページへの誘導のみ)

GitHub Actions側の構成を知りたい方は、Claude Code GitHub Actions解説をご覧ください。

公式ジョブの各行の役割

ジョブは「起動条件」「実行環境の用意」「Claudeの呼び出し」の3段で読めます。公式がコメントで自分用に調整するよう書いているのは rules（“Adjust rules to fit how you want to trigger the job”）で、他の行に調整の指示はありません。下の表の「役割」は、コードと公式コメントからの読みです。

行/ブロック	役割	自分で決めること
`stages` / `stage: ai`	ジョブを置くステージ	既存のステージ構成との並べ方
`image: node:24-alpine3.21`	ジョブを動かすコンテナ	社内で使うイメージの方針
`rules`	起動条件(`web` と `merge_request_event`)。公式コメントが「Adjust rules」と明記	手動、MR、コメントのどれで起動するか
`GIT_STRATEGY: fetch`	リポジトリの取得方法の指定(公式に説明はなく、筆者の読みではRunnerの取得方式の設定)	通常は例のまま
`before_script`	git・curl・bashの導入、インストーラー実行、PATH追記	導入の高速化(公式は「Cache npm and package installs」を挙げる)
`/bin/gitlab-mcp-server \|\| true`	GitLab MCPサーバーの任意起動。公式コメントは「if your setup provides one」の場合としており、失敗しても先へ進む	MCPサーバーを自分の環境で用意できるか
`echo "$AI_FLOW_..."`	トリガー側から渡る入力・文脈・イベントの表示	渡す側の設計
`claude -p`	指示を引数で渡す非対話実行	指示文の内容
`--permission-mode acceptEdits`	権限モードの指定	許可の範囲(後述)
`--allowedTools`	使えるツールの列挙	許可の範囲(後述)
`--debug`	デバッグ出力	ログ量の扱い

${AI_FLOW_INPUT:-'…'} は、公式の説明ではなくシェルの構文からの読みですが、変数が空なら右側の文字列を使う既定値展開です。トリガー側から指示が渡らない実行では、Review this MR and implement the requested changes の文面が指示になります。

手動実行で確認できる範囲

手動実行の成功は、ジョブがエラーなく最後まで完走したことで判定します。これは本記事の定義で、公式は成功を示すログ文言や画面を載せていません。

通し手順は、公式の記載順に3つです。

Settings → CI/CD → Variables を開き、ANTHROPIC_API_KEY を追加する(masked。必要に応じてprotected)。
上のジョブを .gitlab-ci.yml に追加する。
CI/CD → Pipelines から手動でジョブを実行する。

公式の確認文は「手動で実行して試すか、MRから起動して、Claudeにブランチでの更新提案と、必要ならMR作成をさせる」という趣旨です。この2つは成功の中身が違うため、判定を分けておくと迷いません。

実行方法	判定の観点	根拠の強さ
手動実行	ジョブがエラーなく完走した	本記事の定義
MR起点	ブランチへの更新提案、必要に応じたMR作成	公式の文言の範囲

なお、Pipelinesからの手動実行が rules の web に合致する理由は公式に書かれていません。筆者の読みでは、画面からの手動パイプライン実行が web に当たると考えています。失敗したときは、後述の逆引き表から確認箇所を選んでください。

変数と設定の置き場所

秘密情報はSettings → CI/CD → Variablesに、プロバイダーの切り替えフラグなどはジョブの variables: に置きます。認証方式は、長期キーを持つか、OIDCやWIFで一時資格情報にするかで選びます。

OIDCはOpenID Connect、WIFはWorkload Identity Federationの略で、いずれもGitLabジョブが発行するトークンを、クラウド側の一時的な資格情報に交換する仕組みです。公式は「可能ならプロバイダー固有のOIDCを使い、長期キーを避ける」としています。公式にはAmazon Bedrock用とGoogle Cloud’s Agent Platform用の完全なジョブ例まで載っているので、実際の書き方はそちらを写せます。

配置表です。公式の記載位置に従っています。

項目	置き場所	使う場面
`ANTHROPIC_API_KEY`	Settings → CI/CD → Variables(masked)	Claude APIを使うとき。Amazon BedrockとGoogle Cloud’s Agent Platformでは使わない
`GITLAB_ACCESS_TOKEN`	同上(masked)	`api` スコープのProject Access Tokenを使うとき。既定は `CI_JOB_TOKEN`
`AWS_ROLE_TO_ASSUME` / `AWS_REGION`	CI/CD変数(`AWS_REGION` はジョブの `variables:` にも例あり)	Amazon Bedrock
`CLAUDE_CODE_USE_BEDROCK: "1"`	ジョブの `variables:`	Amazon Bedrockを使うジョブ
`GITLAB_OIDC_TOKEN` と `aud`	ジョブの `id_tokens:`。`aud` にはAWS側のIAM OIDCプロバイダーに設定した値を入れる(例ではGitLabインスタンスURL)	Amazon Bedrock
認証情報の交換処理	`before_script`。トークンをファイルに書き、`aws sts assume-role-with-web-identity` で一時資格情報を得て、`AWS_ACCESS_KEY_ID` などをexportする	Amazon Bedrock(公式のジョブ例)
`GCP_WORKLOAD_IDENTITY_PROVIDER` / `GCP_SERVICE_ACCOUNT` / `GCP_PROJECT_ID`	CI/CD変数	Google Cloud’s Agent Platform
`CLOUD_ML_REGION`	CI/CD変数(公式の必須変数一覧に記載。ジョブ例では `variables:` にも `us-east5` を設定)	Google Cloud’s Agent Platform
`CLAUDE_CODE_USE_VERTEX: "1"` / `ANTHROPIC_VERTEX_PROJECT_ID: "$GCP_PROJECT_ID"`	ジョブの `variables:`	Google Cloud’s Agent Platformを使うジョブ
`GITLAB_OIDC_TOKEN` と `aud`	ジョブの `id_tokens:`。`aud` にはWorkload Identity Poolのプロバイダーに設定した値を入れる	Google Cloud’s Agent Platform
認証設定ファイルの作成	`before_script`。トークンを `/tmp/oidc_token` に書き、設定ファイルを作って `GOOGLE_APPLICATION_CREDENTIALS` に指定し、`gcloud auth login` を実行する	Google Cloud’s Agent Platform(公式のジョブ例)
`AI_FLOW_*`	トリガー側から渡される	webやAPI経由の起動

どちらのクラウドを選ぶかの判断は、Amazon Bedrock版とGoogle Cloud版の解説にまとまっています。この節は置き場所の確認用です。

@claudeコメントで起動するための追加要素

コメントでの起動には、最小ジョブに加えて、コメントのイベントを受けて動くリスナーが必要です。公式のManual setup全体は「recommended for production」とされ、その手順4「(Optional) Enable mention-driven triggers」がメンション起動にあたります。手順4の内容は次の2点です。

プロジェクトのwebhookで “Comments (notes)” を、イベントリスナーに向けて追加する(リスナーを使う場合)。
コメントに @claude が含まれるとき、リスナーがパイプラインのトリガーAPIを呼び、AI_FLOW_INPUT や AI_FLOW_CONTEXT などの変数を渡す。

受け取った変数を使って claude -p を実行するのは、手順4の項目ではなく最小ジョブの側の仕事です。上のジョブでは、-p に ${AI_FLOW_INPUT:-…} を渡している行がそれにあたります。webhookは、GitLab上の出来事を外部のURLへ通知する仕組みです。

公式が挙げる指示の例は3種類です。issueのコメントで機能の実装を頼む、MRの議論で実装方針を提案させる、issueやMRのコメントでバグ修正を頼む、という使い方です。いずれも @claude に続けて依頼内容を書きます。

許可ツールの確かめ方

公式の例は acceptEdits モードで、Bash Read Edit Write mcp__gitlab の5つを許可しています。このページには --permission-mode acceptEdits と --allowedTools の各値の定義はなく、表で示した「権限モードの指定」「使えるツールの列挙」より踏み込んだ説明は確認できません。モードの一般的な考え方は権限モードの解説で補えます。

セキュリティに関する記述は、ページ内の出どころごとに分けて読みます。

Best practicesのSecurity considerations: APIキーなどはマスクしたCI/CD変数に置く、可能ならプロバイダー固有のOIDCを使う、ジョブ権限とネットワークのegress(外向き通信)を制限する、ClaudeのMRも他の貢献者のMRと同様にレビューする。
How it works: 各実行は厳格なネットワークとファイルシステムのルールを持つコンテナ内で行われ、書き込みはワークスペース単位の権限で制約される。変更はすべてMR経由なので、差分の確認と承認が効く。
クラウド別の設定: Amazon Bedrockでは信頼ポリシーをプロジェクトとrefに限定して最小権限を付与し、Google Cloud’s Agent Platformでは必要なロールだけを持つ専用サービスアカウントを使う。
Best practicesのCLAUDE.md: リポジトリ直下に置いて規約を与える。書き方はCLAUDE.mdの書き方も参照してください。

許可ツールの影響は、自分のプロジェクトで観察して確かめます。結果は読者自身の観察であり、ここで予測は書きません。

検証用のブランチを作り、その .gitlab-ci.yml に、元のジョブを別名(例: claude-check)でコピーする。同名のままだとキーが重複します。
コピーした側の --allowedTools から Bash を外す。
CI/CD → Pipelines から実行する。元のジョブとコピーの rules が同じ条件(たとえば両方 merge_request_event)に合致すると、2つ走ります。ログはジョブ名で見分けてください。
指示を渡さない実行では、AI_FLOW_INPUT が空なので既定文の指示になります。見比べるときは、同じ指示で揃えてください。
次の3点を見比べる。ジョブが完走するか。--debug のログに現れるツール名がどう変わるか。MRの差分に期待した変更が出るか。

mcp__gitlab は、コメントやMRを書けないときの確認項目として公式のトラブルシューティングに挙がっています。ただし /bin/gitlab-mcp-server は「if your setup provides one」の任意扱いなので、このツールが実際に使えるかは環境次第です。検証で変えるのは Bash 側にとどめると、結果の切り分けがしやすくなります。

費用と実行時間の上限をかける3か所

上限は、claude のフラグ --max-turns、GitLabのジョブレベルの timeout、並行実行の制限の3か所でかけます。費用の構成は、GitLab Runnerの実行時間とトークン消費の2つです。

公式の整理では、Runnerの実行時間はご自身のGitLabプランの課金に、トークン消費はAnthropicの料金ページに従います。トークン消費を抑える一般的な考え方は節約術の解説にもあります。

手段	何を抑えるか	公式の記述
`--max-turns`	往復の回数	「往復の反復回数を制限する」
`timeout`	ジョブ全体の実行時間	`timeout: 30m` は例として記載
並行数の制限	同時に走る実行	「Limit concurrency」
`@claude` の指示を具体的にする	無駄な往復	不要なターンを減らす手段として記載

公式に、値を決める基準となる数値はありません。筆者も数値は示さないので、次の空欄表に、自分のプロジェクトで試して決めた値を書き込んでください。

ジョブ種別	max-turns	timeout	並行数
レビュー
実装
修正

フラグは @anthropic-ai/claude-code のバージョンで変わる可能性があるので、公式は claude --help をジョブ内で実行して確認するよう勧めています。

症状別の確認箇所

症状ごとに見る場所は決まっています。公式のトラブルシューティングは、反応しない、書き込めない、認証エラーの3系統で、エラー全般の切り分けはエラー対処の解説も参照できます。以下に逆引きでまとめます。

症状	確認すること
`@claude` に反応しない	パイプラインが起動しているか(手動、MRイベント、webhook/リスナー)。`ANTHROPIC_API_KEY` またはクラウド側の変数があるか。コメントが `@claude` か(`/claude` ではない)。メンション起動の設定が済んでいるか
コメントやMRを書けない	`CI_JOB_TOKEN` の権限が足りているか、または `api` スコープのProject Access Tokenを使っているか。`--allowedTools` に `mcp__gitlab` があるか。MRの文脈か `AI_FLOW_*` で十分な情報が渡っているか
認証エラー(Claude API)	`ANTHROPIC_API_KEY` が有効で期限切れでないか
認証エラー(Amazon Bedrock / Google Cloud’s Agent Platform)	OIDC/WIFの設定、ロールの引き受け(なりすまし)、シークレット名、リージョンとモデルの提供状況
フラグが通らない	ジョブ内で `claude --help` を実行して、サポートされるオプションを確認する

まとめ

最初の一歩は、公式の最小ジョブを自分の .gitlab-ci.yml に入れ、ANTHROPIC_API_KEY を設定して、Pipelinesから手動で走らせ、完走を確かめることです。そこまで済めば、残りは許可ツール、認証方式、上限値という3つの決めごとに絞られます。

公式の例を自分の手で動かして使えるようになりたい方に向けた、月額1,980円からの学習コミュニティ「AI駆動ラボ」があります。