結論：MR URLを渡す前に、baseと外部操作の境界を決める

Claude Code v2.1.233以降では、GitLab merge requestのURLを--worktreeへ渡し、通常のcheckoutと別directoryで調査・修正できます。ただし安全性はdirectoryを分けるだけでは完成しません。対象MRとcommit、分岐元、読み込む設定、認証情報、許可するGitLab操作、終了後の保存・削除までを先に固定します。

読者の具体的な困りごとは、MRの調査中にmain側の未追跡fileや作業中branchへ変更が混ざり、どの差分がレビュー由来なのか説明できなくなることです。この記事を読むと、local worktree、GitLab CI/CD、通常checkout、HOLDを7軸で選び、MRごとに再現可能な記録を残せます。

次の行動：対象MR URL、期待するbase、実行を許可するcommand、書込可能範囲、終了後のcleanup責任者を一行へ書いてください。

GitLab MR対応の正式条件と制限を確認する

Anthropic公式changelogでは、2026年8月14日公開のClaude Code 2.1.233で、GitLab merge request URLが--worktree flagとclaude agents viewへ追加されました。MRは!Nとして表示されます。versionを確認せず古いclientで試し、URL解釈の失敗をrepository権限の問題だと誤診しないようにします。

worktreeはgit履歴とremoteを共有しながら、作業directoryとbranchを分ける仕組みです。既定ではrepository直下の.claude/worktrees/に作られます。新規worktreeのbaseは通常remoteのdefault branchを使うfreshで、現在の未push commitを必要とする場合だけheadを選びます。MR reviewでbaseを曖昧にすると、差分に本来ない変更が入るため、URL、MR head SHA、target branchを記録します。

対話実行ではworkspace trustが必要です。未確認repositoryなら最初に通常sessionで取得元、owner、commit、.claude設定、Hooks、Skills、MCPを確認します。非対話の-pはtrust確認をskipするため、CIで「promptが出ないから安全」と判断してはいけません。worktreeはfile editをmain checkoutから隔離しますが、remoteへのpush、issueやMR comment、外部MCP操作、credentialのscopeまで別物にする機能ではありません。

GitLab CI/CD連携は公式上betaで、GitLabがmaintenanceを担います。runner内container、masked CI/CD variable、branch protection、MR approvalを使える一方、localの対話確認とは失敗時の責任が違います。機能単体の追加料金は公式に示されず、Claude subscription、Console/API、BedrockまたはGoogle Cloud側の利用条件とtoken費用を確認します。

local worktree・CI/CD・通常checkoutを7軸で比較する

  1. 目的：一回の調査と小さな修正はlocal worktree、同じ条件の自動reviewはCI/CD、単純な閲覧だけなら通常checkoutをread-onlyで使います。
  2. 分離：worktreeはfileとbranch、runnerはprocessとcontainerも分けます。どちらも共有remoteへの権限は別に制限します。
  3. base：worktreeはfresh/head、CIはpipelineのcommit SHAとtarget branchを明示します。
  4. 認証：localはdeveloper credential、CIはmasked variable、OIDC、job tokenまたは期限付きaccess tokenを使います。
  5. 再現性：localは会話とcommand記録が必要で、CIはYAML、image、variable、artifactで再現しやすくなります。
  6. review：local結果は人がdiffを提出し、CI結果はMR上へ集約できます。どちらも最終approvalを置き換えません。
  7. 終了：worktreeは未commit・未追跡・未pushを確認して保存または削除し、CIはartifact・log・temporary credentialの保持期限を決めます。

未知のMR、外部fork、大きな生成file、install script、network accessが含まれる場合は、いきなりdeveloper端末のlocal worktreeで実行しません。read-only調査、隔離runnerまたは使い捨てVMで内容を確認し、必要なtoolだけ許可します。worktreeは便利な衝突防止であり、malicious repositoryを安全化するsandboxの代替ではありません。

GitLab MRを分離してレビューする8手順

  1. MR URL、project path、source・target branch、head SHA、author、forkの有無をGitLab上で確認します。
  2. Claude Codeが2.1.233以降か確認し、install方法とrelease channelを記録します。
  3. repositoryの取得元、.claude配下、Hooks、Skills、MCP、submoduleをread-onlyで調べ、trust可否を決めます。
  4. remote default branchから読むならfresh、手元の未push基盤が必要ならheadを選び、理由を記録します。
  5. GitLab MR URLを--worktreeへ渡し、作成先、branch、現在directory、head SHAが想定どおりか最初に確認します。
  6. permissionをdeny・ask・allowで小さく設定し、push、package install、network、secret読取、MR commentは都度確認に残します。
  7. test、lint、diff、生成物を実行し、MR由来の差分とClaudeが加えた差分を分けて記録します。
  8. 終了時にuntracked file、commit、push有無、残すartifactを確認し、必要なworktreeだけ保存します。削除判断をClaude任せにしません。

GitLab CI/CDへ移す場合は、まずmanual triggerの小さなjobで試します。API keyはmasked・protected variable、cloud providerは可能ならOIDCの短期credential、GitLab API操作はjob tokenまたはproject限定tokenを使います。--allowedToolsを広げず、branch protectionと人間approvalを残してください。

公開・導入前チェックリストとHOLD条件

  • MR URLとhead SHAを記録した
  • source・target branchを確認した
  • 2.1.233以降を確認した
  • fresh/headの理由を書いた
  • repositoryの取得元を確認した
  • workspace trust前に設定を読んだ
  • pushと外部操作をaskに残した
  • credentialをproject範囲へ限定した
  • testとlintを固定した
  • main checkoutへ差分がない
  • untracked fileを確認した
  • cleanup責任者と期限を決めた

HOLDするのは、MRのhead SHAが変わり続ける、外部forkのscriptを内容未確認で実行する、remote push権限が広すぎる、main checkoutに既存dirty差分がある、worktree内の秘密file供給元が不明、削除すると失う作業を判定できない場合です。分離できた表示だけを安全証明にしません。

よくある質問と次の行動

MR番号だけでも指定できますか？

公式worktree guideは番号形式とURL形式を案内します。複数remoteやGitLabを扱う運用では、誤projectを避けるためMR URLとhead SHAを記録する方が明確です。

worktreeを終了すれば自動削除されますか？

cleanな無名sessionは自動cleanupされる場合がありますが、named sessionや変更・commitがある場合は保存判断が必要です。非対話実行では自動cleanupを前提にしません。

GitLab CI/CDならlocal worktreeは不要ですか？

用途が違います。CIは再現可能な自動処理、local worktreeは対話的な調査や修正に向きます。同じMRで両方を使う場合も成果物と責任を分けます。

GitLab MR URL対応とversionはClaude Code公式changelog、base・trust・cleanup・隔離は公式Worktrees guide、runnerとcredential条件は公式GitLab CI/CD guideで公開直前にも確認してください。

trust前の確認はworkspace trustの安全判断、比較対象はGitHub連携、commandと外部操作の境界は権限設定へつなげます。Miraigentの無料診断では、MR取得、隔離、認証、test、review、cleanupを一枚の運用表へ整理します。