結論：marketplaceとpluginの配布元を別々に固定する

GitLabでClaude Code plugin marketplaceを運用する時は、catalog repositoryのURLとref、各plugin sourceのURLとcommit SHA、利用者の認証、組織allowlistを別項目で固定します。2.1.232でGitLab repository URLのclone判定と認証案内が改善されましたが、追加できることと、安全な内容であることは別です。install前にcomponents、Hooks、MCP、権限、更新差分をreviewします。

読者の具体的な困りごとは、private GitLabから配布できても、catalogと実体のどちらが更新されたか、誰のcredentialで取得したか、どのcommitが端末へ入ったか説明できないことです。この記事を読むと、手動追加、組織配布、公開source、配布HOLDを7軸で選べます。

次の行動：一つのpluginについて、marketplace URL、plugin source URL、commit SHA、必要component、取得credential、許可scope、rollback versionを一行へ書いてください。

正式な対応範囲・認証・料金条件を確認する

Claude Codeのmarketplaceはplugin catalogであり、追加しただけではpluginはinstallされません。利用者はmarketplaceを登録し、個別pluginを選んでinstallします。GitHub以外のGit hostもfull repository URLで利用でき、GitLab、Bitbucket、self-hosted serverに対応します。HTTPSまたはSSHのURLを使い、曖昧なhost shorthandを避けます。

2.1.232のchangelogでは、GitLab plugin marketplaceがbare gitlab.com repository URLをGitHub URLと同様にcloneし、nested subgroupも扱い、認証失敗時に実際のGit hostを示すようになりました。同時にadditionalMarketplacesとallowedMarketplacesが従来設定の読みやすいaliasとして追加されています。古いclientとの差を避けるためversionを固定します。

手動のadd・install・updateでは、Claude Codeは既存のgit credential helperを使います。SSHはhostがknown_hostsにありkeyがagentへload済みであることが必要です。tokenをURL、marketplace.json、plugin fileへ書きません。HTTPS rewriteを使う場合もrepository pathへ限定し、read-only tokenにします。

marketplace機能単体の追加料金は公式docsに示されていません。ただしpluginはSkills、agents、Hooks、MCP・LSP serverを追加し、context cost、外部service利用料、model token、GitLab hosting・runner費用が発生し得ます。Team・EnterpriseのOrganization settings経由ではGitHub AppまたはGitHub Enterprise Appを使う配布条件があり、他host上のprivate sourceはそのまま組織syncできない場合があります。手動GitLab運用と管理画面配布を混同しません。

GitLab配布を7軸で設計する

  1. catalog：.claude-plugin/marketplace.jsonのrepository、owner、reviewer、release refを固定します。
  2. source：各pluginの実体URLをcatalogと分け、可能ならfull 40文字commit SHAへpinします。
  3. 認証：個人credential、deploy token、CI credentialを用途別にし、read-onlyと期限を設定します。
  4. 内容：Skills、agents、Hooks、MCP、LSP、command、dependencyをinstall前に一覧化します。
  5. policy：許可marketplaceをexact URLまたはhost patternで限定し、blocklistと例外承認を用意します。
  6. 更新：catalog refreshとplugin updateを別changeとしてreviewし、versionとSHAの差分を残します。
  7. 復旧：旧SHA、cache、無効化、削除、credential revoke、影響端末一覧をrollback手順へ入れます。

marketplace sourceとplugin sourceは別物です。marketplaceはcatalogの取得元で、個別pluginはcatalog内のsourceから取得されます。catalogを固定しても、plugin sourceが動くbranchだけなら内容は変わります。反対にpluginをSHA pinしても、catalog側で別sourceへ差し替えられるため、両方のreviewが必要です。

private GitLab marketplaceを導入する8手順

  1. Claude Code 2.1.232以降をcanary端末へ固定し、install方法、release channel、rollback versionを記録します。
  2. GitLab projectのvisibility、owner、protected branch、CODEOWNERS、merge approval、audit eventを確認します。
  3. marketplace.jsonと各plugin.jsonをvalidateし、source、version、components、外部dependencyを一覧化します。
  4. plugin sourceをfull URLとcommit SHAへpinし、tagやbranchを使う場合は変更検知と再reviewを必須にします。
  5. canary利用者へread-only credentialまたはSSH keyを設定し、tokenがconfig、log、shell historyへ残らないか確認します。
  6. managed settingsで許可sourceを限定し、URL表記差、.git、HTTPS・SSH、subgroupを実際の取得形と合わせます。
  7. 一つのpluginだけinstallし、追加されたSkill、agent、Hook、MCP、command、context cost、network accessをreadbackします。
  8. 更新、無効化、削除、旧SHAへの復旧、credential revokeを試し、全端末展開かHOLDかを決めます。

allowlistはnetwork operation前に確認されますが、許可されたrepositoryの内容を安全と保証しません。source URLの表記差はexact matchで別物になることがあります。組織内GitLab host全体をpattern許可すると新しいrepositoryまで入るため、最初はcatalog repository単位で限定し、例外は期限付きにします。

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

  • 2.1.232以降を確認した
  • catalog ownerを確認した
  • protected branchを設定した
  • reviewerを二名以上置いた
  • plugin sourceを分けて記録した
  • commit SHAへpinした
  • read-only credentialを使った
  • tokenをfileへ埋めていない
  • Skillsとagentsを読んだ
  • HooksとMCPを読んだ
  • 外部network先を確認した
  • allowlistを限定した
  • 更新差分を保存した
  • 旧versionへ戻せた

HOLDするのは、source ownerが不明、plugin実体が動くbranchだけ、install時に外部scriptを内容未確認で実行する、personal tokenがcatalogへ入る、self-hosted GitLabのTLS・host keyを検証できない、Organization settingsの配布条件を手動installと混同する、rollback用SHAがない場合です。clone成功やvalidate PASSだけを安全証明にしません。

よくある質問と次の行動

GitLabのgroup URLだけで追加できますか？

marketplace catalogを持つ具体的repository URLを指定します。nested subgroupを含む場合も、実際のclone URLとallowlist表記を一致させます。

private repositoryなら安全ですか？

公開範囲が狭いだけで、内容の安全性は保証しません。review、SHA pin、最小credential、更新承認が必要です。

pluginをZIP配布する方法とどちらを選びますか？

GitLab marketplaceは継続更新と複数pluginのcatalogに向き、archiveは一回の固定artifact配布に向きます。更新責任と検証方法で選びます。

GitLab URL、認証、追加操作はClaude Code公式plugin discovery guide、catalog、source pin、policy、private repository条件は公式marketplace guide、2.1.232の変更は公式changelogで公開直前にも確認してください。

固定artifact配布はpluginのZIP配布、plugin内Skillの確認はSkillsの出所管理、repository trustはworkspace trustへつなげます。Miraigentの無料診断では、catalog、source、認証、component、policy、rollbackを一枚の運用表へ整理します。