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

GitLabで使える機能とその必要バージョン

GitLabリポジトリの対話セッションで働く仕組みは5つあります。マージリクエストからのワークツリー分岐、URLによるセッション検索、プラグインマーケットプレイスのGitLabホスト対応。フッターとstatuslineのマージリクエストバッジ、glabのトークン保護もあります。

追加されたバージョンはばらばらです。ドキュメント通りにコマンドを打って反応しないときは、まずバージョンを疑います。

claude --version

2.1.285 (Claude Code)

マージリクエストバッジの色分けとレビュー状態はClaude Code PRレビューステータスの見方(GitHub/GitLab)、GitLab CI/CDで@claudeメンションから実装を自動化する設定はClaude CodeをGitLab CI/CDに組み込むで扱っています。ここでは手元の対話セッションに絞ります。

マージリクエストの続きを手元で再開したい

--worktreeにマージリクエストの番号かURLを渡すと、Claude Codeはその先頭コミットをoriginから取得し、.claude/worktrees/pr-<番号>にワークツリーを作ります。v2.1.233からの機能です。

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

#はシェルにコメントと解釈されるので、番号で渡すときは必ずクォートします。URLからは番号だけが読み取られ、フェッチ先はoriginのホストで決まります。

自己ホスト環境はURLからGitHub系かGitLab系か判別できないため、初回は2段階のフェッチになります。作成が一瞬もたつくのは故障ではありません。v2.1.233より前は#<number>とGitHub形式のURLしか受け付けず、pull/<number>/headだけを取得していました。

同じ名前で開き直したとき、既定のbaseがfreshで、未コミットの変更や未追跡ファイルが無く、作成時のブランチのままなら、ワークツリーがデフォルトブランチへリセットされることがあります。手元に自前のコミットが無いか、マージリクエストがマージ済みでリモートブランチが消えている場合です。

名前がマージリクエスト参照のとき、この作り直しは働かず古い先端のまま開き直します。

前回の作業セッションに戻りたいなら、--from-prにURLか番号を渡します。

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

claude --helpの説明は「PR number/URL, or open interactive picker with optional search term」(v2.1.285で確認)で、値を省くと絞り込み付きの選択画面が開き、値を渡した場合も、そのPRに紐付いたセッションに絞った選択画面になります。GitHub・GitHub Enterprise・GitLab・BitbucketのURLを受け付け、対話セッションの/resumeの検索窓にURLを貼っても同じセッションが見つかります。Claudeが作ったマージリクエストは自動でセッションに紐付きます。デスクトップアプリのCodeタブで自己ホストGitLabのMRが紐付かないときは、Claude DesktopでGitLabのMRが紐付かない場合の切り分けを参照してください。

マージリクエストのバッジが出ない

バッジが出る条件は3つで、どれかが欠けると出ません。

GITLAB_TOKENのような環境変数は、状態確認の時点では無視されます。トークンをexportしただけではバッジは出ません。

バッジの下線は、GitLabがマージ可能と報告していれば緑、それ以外の開いた状態なら黄色、ドラフトなら灰色です。git pushや、状態を変えるglab mr create glab mr mergeが成功するとすぐ更新されます。statuslineのスクリプトからは、pr.numberとpr.kind(mr)でマージリクエストを判別できます。

glab mrのcreate merge close reopen note updateは、v2.1.259からツールの折りたたみ表示でもMR !Nとして認識されます。/code-review --commentは、v2.1.257でGitLabのマージリクエストにglab mr noteでコメントを投稿するようになりました。それ以前は投稿先として未対応と報告していました。

自己ホストGitLabのプラグインを追加したい

https://付きの完全なクローンURLか、SSHならgit@host:pathの形で渡せば、GitHubと同じ手順で追加できます。v2.1.232からは、gitlab.comのURL(入れ子のサブグループを含む)もgithub.comと同じようにクローンされます。

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

自己ホストでは、スキームを省いたgitlab.example.com/team/pluginsは、owner/repoという省略形として扱われて弾かれます。v2.1.285で実際に出たメッセージは次のとおりです。

✘ 'gitlab.example.com/team/plugins' is not a valid GitHub owner/repo shorthand. For a git repo, use the full https:// clone URL from your host (typically ending in .git — some hosts like Azure DevOps omit it). For a hosted marketplace.json, use its https:// URL. For a local path, use ./ or an absolute path.

claude plugin marketplace add --helpは、--scope(user・project・local。既定はuser)と、モノレポ向けに取得先を絞る--sparseを持っています(v2.1.285で確認)。

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

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

組織のポリシーで追加先を制限している場合は、hostPatternでGitLabサーバーごと許可できます。

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

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

非公開リポジトリの認証は2通りある

バックグラウンドの自動更新はマーケットプレイスごとの設定で、非公開のHTTPSリモートでは、認証情報ヘルパーに認証情報が保存済みのときだけ通ります。バックグラウンドのチェックが失敗しても既存のチェックアウトを保ちたいときは、環境変数CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1を設定します。ネットワークに届かない環境でも、以前取得したマーケットプレイスが使い続けられます。

トークンはコマンド出力からどう隠れるか

v2.1.232から、GitLabのトークン形式がコマンド出力やログでマスクされます。対象はglrt- gloas- glptt- glagent- glimt- glsoat- glcbt- glft- glffct-の系列です。

glpat-(個人アクセストークン)とgldt-(デプロイトークン)は、routable形式のものが完全にマスクされます。glabの設定ストアも、ghと同じサンドボックスと認証情報パスの保護を受けます。

GitHub前提の表示と、リポジトリの検出

v2.1.233から、originがgitlab.comかbitbucket.orgのリポジトリではGitHub Appの導入を勧めるヒントが出なくなりました。代わりに、エンタープライズ向けマーケットプレイスのヒントが非GitHubの社内gitホストをカバーします。v2.1.259では、GitLabリポジトリで/install-github-appを実行すると、GitHub専用であることを伝えてGitLab CI/CDのドキュメントを案内するようになりました。

v2.1.260では、gitlab.com上のサブグループが入れ子になったプロジェクトが正しく検出されるようになりました。statuslineのJSONのworkspace.repoもこの構成で埋まり、ownerはgroup/subgroupのようにスラッシュ区切りの名前空間全体です。v2.1.260より前は、これらのプロジェクトでworkspace.repoが空でした。

Claudeの回答に出るowner/repo#123形式の課題参照は、gitlab.comのリポジトリなら、https://gitlab.com/owner/repo/-/issues/123にリンクされます。ただし、リンクになるのは2階層の形だけです。#123だけの参照や、group/subgroup/project#123のような入れ子のパスはリンクになりません。Bitbucketも、リンクはできません。

まとめ

全機能を使うならv2.1.234以降と認証済みのglabが要ります。マーケットプレイスとトークン保護だけならv2.1.232、ワークツリー分岐はv2.1.233で足ります。Bitbucketでは--from-prのURL検索は通りますが、バッジは公式ドキュメントにGitHubとGitLabしか載っていません。