GHESプラグインマーケットプレイスを許可リストで運用する — 管理者向け設定ガイド

GHESプラグインマーケットプレイスの許可リスト運用でできること

GitHub Enterprise Server(GHES)上に社内向けプラグインマーケットプレイスをホストしている組織は、managed-settings.json(またはMDMの同等ポリシー)に1行のhostPattern設定を足すだけで済みます。これでGHESインスタンス上の全リポジトリをマーケットプレイスとして許可できます。個々のリポジトリを1件ずつ許可リストへ列挙する必要はありません。構造自体はgithub.comホストのマーケットプレイスと同じです。ただしGHESではインストール方法と必要な認証情報が使う面(surface)ごとに変わるため、CLIだけを想定した設計だとclaude.aiやWebセッションで失敗します。チームに自動配布したいならextraKnownMarketplacesの設定手順が参考になります。

managed settingsでマーケットプレイスを制限している組織がこの許可リストを設定していないと、開発者が/plugin marketplace addを実行してもポリシーエラーで弾かれます。逆に言えば、社内マーケットプレイスを配布したいなら許可リストの設定は前提条件です。

開発者の追加が失敗するとき、どこから疑うか

症状ごとに、原因の置き場所が違います。上から順に当てはめると切り分けが早く済みます。

面ごとに何が必要か

同じGHESマーケットプレイスでも、どこから追加するかでインストールの仕組みと開発者に必要なものが変わります。

クラウドセッションでのマーケットプレイス追加は避けます。セッションのgit認証情報はそのセッションのリポジトリに限定されており、別ホストはもちろん同一GHESインスタンスでも安定してインストールできません。CLI・managed settings・claude.aiのいずれかを使います。

GHES接続の管理者セットアップは組織単位ですが、個々のユーザーの接続は肩代わりしません。Ownerが組織プラグイン設定側で追加すれば、以降のユーザーは個人接続なしに使えます。

claude.aiの画面にある「Connect to GitHub」ボタンはgithub.comへのサインインです。GHESへのアクセスは別の接続になり、claude.ai/codeのリポジトリ選択画面か、Ownerなら管理設定のGitHub Enterpriseの節から接続します。GHESがAnthropicのインフラから届かないときは、ファイアウォールでAnthropicの送信元IPアドレスからの接続を許可します。

GHESマーケットプレイスを追加する

owner/repoの省略記法は常にgithub.comを指すため、GHESホストのマーケットプレイスはフルのgit URLで指定します。

/plugin marketplace add https://github.example.com/platform/claude-plugins.git

SSH URLもマシンが対象GHESホストを信頼済みなら使えますが、Claude Codeはgitを非対話で実行するためknown_hostsに無いホストへのSSH接続を拒否します。git credential helperと組み合わせたHTTPS URLならknown_hostsの登録が不要になり、運用が安定します。

シェルから同じ操作をするコマンドはclaude plugin marketplace addです。v2.1.289で--helpを実行すると、次のオプションが並びます。

claude plugin marketplace add --help

Usage: claude plugin marketplace add [options] <source>
 
Add a marketplace from a URL, path, or GitHub repo
 
Options:
  --claudeai           Add the marketplace of this name that claude.ai hosts for
                       you, by its listed name or its local name (see: claude
                       plugin marketplace list)
  --json               Print one machine-readable result line as the last line
                       on stdout (same exit codes)
  --scope <scope>      Where to declare the marketplace: user (default),
                       project, or local
  --sparse <paths...>  Limit checkout to specific directories via git
                       sparse-checkout (for monorepos). Example: --sparse
                       .claude-plugin plugins

--scopeの既定はuserです。チーム共有の設定ファイルに書き込みたいときは--scope projectを指定します。--jsonを付けると最終行に結果が1行で出ます。listサブコマンドにも--jsonがあります。

managed settingsで組織展開する

以下はmanaged-settings.json(または各OSのMDMポリシー)に書く2つのキーに絞った説明です。managed settingsの階層構造や他の統制項目全般はClaude Code組織管理ガイドにまとめています。

事前登録(pre-register)で自動配布する

extraKnownMarketplacesは、開発者が手動で追加しなくてもマーケットプレイスを使える状態にする設定です。リポジトリの.claude/settings.jsonを含む任意の設定ファイルで有効ですが、managed settingsで配れば組織全体に届きます。

{
  "extraKnownMarketplaces": {
    "internal-tools": {
      "source": {
        "source": "git",
        "url": "https://github.example.com/platform/claude-plugins.git"
      }
    }
  }
}

この経路はclaude.aiを経由しないため、per-userのGitHub Enterprise接続は不要です。Claude Codeがエントリを登録し、マシンの既存git認証情報でリポジトリをクローンします。展開が止まりやすいのは、設定が各マシンに届いていない場合です。managed settingsファイルは、デバイス管理システム等で配布した先のマシンにしか効きません。

hostPatternで許可リストを組む

managed settingsでマーケットプレイスの追加元を制限している組織は、hostPatternソースタイプを使うと、GHESインスタンスのリポジトリを1件ずつ列挙せずにまとめて許可できます。

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

hostPatternは正規表現で、マーケットプレイスのホスト名のどこかに当たれば一致します。^と$で両端を固定しないと、ホスト名の一部に当たるだけで許可されます。たとえばgithub\\.example\\.comとだけ書くと、github.example.com.example.netのようなホストも通ります。

GHESインスタンスが複数ある場合はパターン側で複数ホストにマッチさせるか、エントリを追加します。strictKnownMarketplacesはallowedMarketplacesという別名でも書けます(Claude Code v2.1.232以降)。古いバージョンは別名を読まないため、新旧が混在するマシンに配る設定ファイルはstrictKnownMarketplacesのまま書きます。

hostPatternはGHESに限りません。社内でホストしているGitLabサーバー等にも同じ書き方で許可リストを組めます。

hostPatternがマッチしないgit URLの形式に注意

hostPatternはマーケットプレイスのソースからホスト名を取り出して正規表現と照合しますが、ホストを取り出せる形式は限られています。

HTTPS URLが推奨なのは、known_hostsを避けられるためです。許可リストを入れる前に、社内の手順書に残っているgit@host:pathでもhttps://でもない書き方(スキームなしのその他の形式)を洗い出しておくと、導入後のポリシーエラーが減ります。v2.1.234より前のバージョンでは、gitがSSHアドレスとみなさない一部の形式にもhostPatternが一致していました。

許可リストに足すエントリは用途で選ぶ

hostPattern以外のエントリは、1リポジトリ単位で厳密に絞りたいときに使います。GHES上の特定のリポジトリだけ許可するならgitソースでURLを書きます。

{
  "strictKnownMarketplaces": [
    {
      "source": "git",
      "url": "https://github.example.com/platform/claude-plugins.git"
    }
  ]
}

gitエントリは完全一致です。urlが一字違えば別のソースとして扱われ、refやpathを書いたエントリは、同じ値を持つソースにしか当たりません。ブランチ違いのマーケットプレイスを並べる組織は、refごとにエントリを書くか、hostPatternでホスト単位に広げるかを決めておく必要があります。

許可した中から特定のソースだけ止めたいときは、blockedMarketplacesを併用します。ブロックリストは許可リストより先に評価されます。すでに登録済みのマーケットプレイスでも、ブロックリストのソースに一致すれば更新や自動更新での取得が止まります。

strictKnownMarketplacesだけでは自動登録されない

strictKnownMarketplacesは追加を許可するかどうかだけを判定する関門で、何かを登録するわけではありません。これだけを設定した場合、許可されたGHESマーケットプレイスであっても、開発者が/plugin marketplace addを自分で実行するまでは使えるようになりません。自動登録されるのは公式Anthropicマーケットプレイスだけで、それも許可リストが許可している場合に限られます。

GHESマーケットプレイスを「許可するだけでなく全員に自動配布する」には、同じmanaged-settings.jsonにextraKnownMarketplacesも設定します。

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ],
  "extraKnownMarketplaces": {
    "internal-tools": {
      "source": {
        "source": "git",
        "url": "https://github.example.com/platform/claude-plugins.git"
      }
    }
  }
}

strictKnownMarketplacesが制限、extraKnownMarketplacesが配布という役割分担です。前者は追加の可否を判定し、後者はマーケットプレイスを各マシンに登録します。

hostPatternだけの許可リストは、公式マーケットプレイスも止める

上の例の許可リストにはGHESしか書いていません。許可リストに載らないソースはすべて拒否されるため、公式Anthropicマーケットプレイスの追加も止まります。空配列[]は、公式マーケットプレイスを含む全ソースを止める完全ロックダウンです。キー自体を書かなければ、誰でも任意のマーケットプレイスを追加できる既定の状態のままです。

公式マーケットプレイスと社内のGHESを両方使わせたいときは、リポジトリanthropics/claude-plugins-officialも許可リストに並べます。許可リストは空配列を含むどんなものでも~/.claude/skills/の@skills-dirプラグインの読み込みを止めるので、残したければskills-dirのエントリも足します。

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "anthropics/claude-plugins-official" },
    { "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" },
    { "source": "skills-dir" }
  ]
}

公式マーケットプレイスの自動登録は、新しいマシンで最初に対話ターミナルのセッションを開いたときに行われます。起動前に走る非対話の環境、VS Code拡張でしか動かしていないマシン、空配列のロックダウン下で一度でも対話セッションを開いたマシンでは、登録が起きないことがあります。確実に配るならextraKnownMarketplacesに書くか、claude plugin marketplace add anthropics/claude-plugins-officialを実行します。

許可リストを入れた後の挙動

strictKnownMarketplacesは、マーケットプレイスの追加時だけでなく、プラグインのインストール・更新・refresh・自動更新のたびに、ネットワークやファイルシステムの操作より前に評価されます。ポリシー設定前に追加されたマーケットプレイスでも、ソースが許可リストに一致しなくなった時点でプラグインの取得ができなくなります。

セッションの開始時にも、インストール済みのプラグインに同じ判定がかかります。許可リストと合わなくなったプラグインは読み込まれず、/pluginの一覧に次のいずれかが出ます。

Marketplace "<name>" is not in the allowed marketplace list
Marketplace "<name>" is blocked by enterprise policy

許可リストを設定している間は、マーケットプレイスが見つからないプラグインも「見つからない」ではなくポリシーエラーで表示されます。登録されていないマーケットプレイスを指す古いenabledPluginsのエントリが、典型的な原因です。

許可リストを迂回する経路にも注意が要ります。--plugin-dirや--plugin-urlなどのフラグを付けると、ユーザーは1回の実行に限って許可リストを避けられます。disableSideloadFlagsをtrueにすると、--plugin-dir・--plugin-url・--agents・--mcp-configの各フラグが起動時に拒否されます。この設定はv2.1.193以降が必要です。

書く場所でclaude.aiへの効き方が変わる

同じstrictKnownMarketplacesでも、書く場所で効く範囲が変わります。

管理コンソール側に書いた場合、claude.aiは組織全体向けの追加も、メンバーが自分用に追加する場合も、許可リストに合わないリポジトリを拒否します。ただし、リストを設定する前に追加済みのマーケットプレイスは再判定せず、アップロードされたプラグインも対象外です。

使い分け早見表

プラグインまで強制導入するならenabledPluginsも併用します。全員に配る標準マーケットプレイス以外の社内マーケットプレイスはhostPatternで許可だけしておいて開発者の任意追加に任せる、という組み合わせが実務では扱いやすい構成です。

まとめ

GHESのマーケットプレイスは、許可はhostPattern、配布はextraKnownMarketplacesと分けて設計し、許可リストに公式マーケットプレイスとskills-dirを入れ忘れないことが要点です。claude.ai経由で使わせる組織は、個人接続が要るユーザー設定と、Ownerが追加する組織設定のどちらを案内するかを先に決めておくと、問い合わせが減ります。

マーケットプレイス自体の作り方はClaude Codeプラグイン完全ガイドにあります。GHES接続の管理者セットアップはGitHub Enterprise ServerでClaude Codeを使うにあります。MCPサーバーの組織的な許可リスト運用はManaged MCPで許可リスト・拒否リストを組織管理するで扱っています。