Claude Code GitLab連携ガイド — glab CLIとMR紐付け

Claude CodeはGitLabのどこに対応しているか

対話セッションでGitLabリポジトリを使うとき、Claude Codeは5つの独立した仕組みでGitLabを扱えます。マージリクエストからのワークツリー分岐、URLによるセッション検索、プラグインマーケットプレイスのGitLabホスト対応、フッターとstatuslineのマージリクエストバッジ、そしてglab CLIが扱うトークンのシークレットマスキングです。

それぞれ追加されたバージョンが異なります。フッターバッジだけを見るとv2.1.234が必要ですが、--worktreeでのマージリクエスト分岐はv2.1.233から、マーケットプレイスのGitLab対応とトークン保護はv2.1.232から動きます。古いバージョンのままだと、ドキュメント通りにコマンドを打っても反応しないことがあります。

マージリクエストバッジの色分けとレビュー状態の詳細はClaude Code PRレビューステータスの見方(GitHub/GitLab)、GitLab CI/CDのパイプラインで@claudeメンションから実装を自動化する設定はClaude CodeをGitLab CI/CDに組み込むで扱っています。本記事は、ローカルの対話セッションでGitLabリポジトリを使う際の設定と挙動に絞ります。

マージリクエスト番号からワークツリーを作る

--worktreeにマージリクエストの番号かURLを渡すと、Claude Codeはそのマージリクエストの先頭コミットをoriginから取得してワークツリーを作成します。対応はv2.1.233からです。

claude --worktree "#123"

シェルが#をコメントの開始と解釈しないよう、引数は必ずクォートします。マージリクエストのURLをそのまま渡すことも可能です。

claude --worktree "https://gitlab.com/group/repo/-/merge_requests/123"

Claude CodeはURLから番号だけを読み取り、originリモートのホストに応じてフェッチ先を切り替えます。

自己ホストのGitシステムはURLだけでは種類を判別できないため、2段階のフェッチになります。初回のワークツリー作成が一瞬もたつくのはこのためです。v2.1.233より前は#<number>とGitHub形式のプルリクエストURLしか受け付けず、常にpull/<number>/headだけをフェッチしていました。

作成したワークツリーは.claude/worktrees/pr-<number>に置かれます。マージ済みで名前を再利用した場合、リモートブランチが消えていて手元のコミットがすべてデフォルトブランチに含まれていれば、Claude Codeはリセットして作り直します。それ以外のケース(マージリクエスト参照名を含む)では、古い先端コミットのまま再オープンします。

セッションをマージリクエストのURLで検索する

--from-prと/resumeの検索窓は、貼り付けたURLがGitHub・GitHub Enterprise・GitLab・Bitbucketのどれであっても対応するセッションを見つけます。番号だけを渡すこともできます。

claude --from-pr "https://gitlab.com/group/repo/-/merge_requests/123"

Claudeが作成したプルリクエストやマージリクエストは自動的にセッションへ紐付くため、あとから番号やURLで呼び出せます。対話セッション内で/resumeを開き、検索モードにマージリクエストのURLを貼り付けても同じセッションが見つかります。

自己ホストGitLabでプラグインマーケットプレイスを追加する

GitLabでホストしたプラグインマーケットプレイスは、ベアリポジトリのURLを渡すだけでGitHubのマーケットプレイスと同じ手順で追加できます。v2.1.232からは、gitlab.comのベアリポジトリのURL(入れ子のサブグループを含む)もgithub.comのURLと同じようにクローンされます。

/plugin marketplace add https://gitlab.com/company/plugins.git

自己ホストのGitLabインスタンスも同様に扱えます。

claude plugin marketplace add https://gitlab.example.com/team/plugins.git

v2.1.196以降、gitlab.example.com/team/pluginsのようにスキームを省いた書き方は、GitHubのowner/repo省略形として誤読されずに明確なエラーになります。https://を付けるか、ローカルパスなら./で始めます。

特定のブランチやタグに固定したいときは、settings.jsonでgitソースタイプを使います。

{
  "source": "git",
  "url": "https://gitlab.example.com/tools/plugins.git",
  "ref": "production"
}

gitソースタイプは自己ホストGitLabやBitbucketを含む任意のgitホスティングで動きます。認証は、そのマシンでgit cloneが使うのと同じ仕組み(認証情報ヘルパーやSSH鍵)に従います。GITLAB_TOKENのような環境変数を設定しただけでは効かず、その変数を読む認証情報ヘルパーを経由して初めて反映されます。

組織のポリシーで追加できるマーケットプレイスを制限している場合、リポジトリを1件ずつ列挙する代わりにhostPatternで自己ホストGitLabサーバーごと許可できます。

{
  "source": "hostPattern",
  "hostPattern": "^gitlab\\.example\\.com$"
}

hostPatternが見るホスト名は、URLの形によって取り方が変わります。https://のようなスキーム付きURLはそのままホスト名を、git@git.example.com:tools/plugins.gitのようなスキーム省略のSSHアドレスは@と:の間を、それ以外のスキームなし表記はホストが取れずstrictKnownMarketplaces側のhostPatternにはどれも一致しません。

glabのトークンはどう保護されるか

v2.1.232で、Claude CodeはGitLabのトークン形式を認識し、コマンド出力やログからマスクするようになりました。対象はglrt- gloas- glptt- glagent- glimt- glsoat- glcbt- glft- glffct-のトークン系列です。

このうち、個人アクセストークンとデプロイトークンにあたるglpat-とgldt-は完全にマスクされます。どちらもそのままAPI呼び出しに使える(ルーティング可能な)トークンで、断片が漏れただけでも悪用の起点になり得るためです。あわせて、glab CLIの設定ストアもghと同じサンドボックスと認証情報パスの保護を受けるようになりました。

GitLabサポートはどう広がってきたか

機能ごとに必要バージョンが異なるため、まとめて見比べると導入計画が立てやすくなります。

同じv2.1.233では、GitHub App導入を勧めるヒントが、originがgitlab.comまたはbitbucket.orgのリポジトリでは表示されなくなり、代わりにエンタープライズ向けマーケットプレイスのヒントが非GitHubの社内gitホストをカバーするようになりました。GitHub前提の案内が非GitHubリポジトリに紛れ込む場面が減っています。

よくあるつまずき

• --worktree "#123"のクォート漏れ: クォートを外すとシェルが#以降をコメント扱いし、番号が渡りません
• フッターにマージリクエストバッジが出ない: GITLAB_TOKENのような環境変数を設定しただけでは認証と見なされません。glab auth loginが必要で、glabのインストールやログイン後はClaude Codeの再起動が要ります(セッション開始時に一度だけ検出するため)
• マーケットプレイスURLのスキーム省略: gitlab.example.com/team/pluginsのようにスキームを省くとエラーになります。https://を付けるか、ローカルパスなら./を使います
• 自己ホストGitLabやGitHub Enterpriseでのワークツリー作成が一瞬遅い: フェッチ先の判定がpull/<number>/head→merge-requests/<number>/headの2段階になるためで、故障ではありません
• strictKnownMarketplacesでGitLabがブロックされる: リポジトリを1件ずつ許可リストに書く代わりにhostPatternでホストごと許可していないと、マーケットプレイスの追加自体が拒否されます

まとめ

Claude CodeのGitLab対応は、ワークツリー分岐・セッション検索・プラグインマーケットプレイス・フッターバッジ・トークン保護がそれぞれ別のバージョンで追加されてきました。最新の全機能を使うにはv2.1.234以降が必要で、マージリクエストバッジには加えて認証済みのglab CLIが要ります。マーケットプレイスとトークン保護だけならv2.1.232、ワークツリー分岐はv2.1.233で動きます。手元のバージョンと照らし合わせて、足りない機能があればアップデートを検討してください。

よくある質問

Bitbucketでも同じように使えますか

--from-prと/resumeの検索はBitbucketのプルリクエストURLにも対応しています。--worktreeのマージリクエスト分岐も、GitHub Enterprise・自己ホストGitLab以外の「その他のホスト」としてpull/<number>/head→merge-requests/<number>/headの順で試すフォールバックの対象です。ただしフッターのマージリクエストバッジはGitHubのプルリクエストとGitLabのマージリクエストに対応しており、Bitbucket向けのバッジは公式ドキュメントに記載がありません。

自己ホストのGitLabインスタンスでも全部使えますか

はい。gitlab.comだけでなく、自己ホストのGitLabインスタンスを指すリモートにもワークツリー分岐とマージリクエストバッジは対応しています。プラグインマーケットプレイスも、gitソースタイプとhostPatternの組み合わせで自己ホスト環境を扱えます。

非公開のGitLabリポジトリからプラグインを配布できますか

できます。git cloneと同じ認証情報ヘルパーやSSH鍵を使います。ただし、バックグラウンドの自動更新はgit pull実行時に認証情報ヘルパーを無効化するため、HTTPS経由の非公開リポジトリでは自動更新が失敗することがあります。グローバルなgit URL書き換えでトークンをURLに埋め込む(GitLabならhttps://oauth2:TOKEN@gitlab.com/...の形式)と、バックグラウンド更新でも認証できます。

GitLab CI/CDでも@claudeメンションから自動化できますか

できます。CI/CDジョブとしてClaude Codeを動かし、Issueやマージリクエストのコメントから実装・修正・マージリクエスト作成を自動化する仕組みがあります。パイプライン側の設定はClaude CodeをGitLab CI/CDに組み込むにまとめています。本記事が扱うのは、開発者が手元で対話セッションを動かすときのGitLab連携です。