Héberger et maintenir une marketplace

​

Héberger votre marketplace

​

Enregistrer la marketplace pour tout le monde dans un référentiel

​

Éviter les entrées de chemin relatif dans une marketplace hébergée sur URL

​

Éditer les plugins sur place dans un répertoire partagé

​

Garder les fichiers de plugin hors de Git LFS

​

Partager les fichiers au sein d’une marketplace avec des liens symboliques

• Au sein du répertoire du plugin lui-même : le lien symbolique est préservé en tant que lien symbolique relatif dans le cache, donc il continue à se résoudre à la cible copiée au moment de l’exécution.
• Ailleurs au sein de la même marketplace : le lien symbolique est déréférencé. Le contenu de la cible est copié dans le cache à sa place. Cela permet au répertoire skills/ d’un meta-plugin de se lier aux compétences définies par d’autres plugins dans la marketplace.
• En dehors de la marketplace : le lien symbolique est ignoré pour des raisons de sécurité.

ln -s ../../shared-plugin/skills/foo ./skills/foo

​

Distribuer via les paramètres de l’organisation

• Référentiel de marketplace : sur github.com et gitlab.com, il doit être privé ou interne
• Sources de plugin : chaque source de plugin doit être de type github, url, ou git-subdir, ou un chemin relatif qui commence par ./
• Répertoire bin/ de niveau supérieur : claude.ai rejette un plugin qui en a un et synchronise le reste de la marketplace. Le message d’erreur commence par Plugin contains a top-level bin/ directory. Gardez les exécutables dans un autre répertoire, comme scripts/, et référencez-les comme ${CLAUDE_PLUGIN_ROOT}/scripts/<name> depuis vos hooks ou configurations de serveur MCP

​

Accorder l’accès à une marketplace privée

• GitHub owner/repo : Claude Code sonde ssh -T git@github.com et clone sur SSH quand la sonde réussit. Si la sonde échoue, ou le clone SSH lui-même échoue, il clone sur HTTPS. Les utilisateurs sur des machines sans clé SSH GitHub peuvent définir CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 pour ignorer la sonde et cloner sur HTTPS.
• git@host:path.git : SSH.
• https://example.com/repo.git : HTTPS.

• SSH : la clé doit fonctionner sans invite de phrase secrète, par exemple parce qu’elle est chargée dans ssh-agent. L’hôte doit déjà être dans known_hosts.
• HTTPS : Claude Code laisse l’assistant d’identifiants git de l’utilisateur activé mais lui interdit de demander. Un identifiant que l’assistant stocke déjà fonctionne ; un qu’il devrait demander échoue. Sur GitHub, gh auth login suivi de gh auth setup-git en stocke un.

​

Servir les utilisateurs qui n’ont pas de compte sur l’hôte git

• archive : un zip téléchargé sur HTTPS. Les utilisateurs n’ont besoin ni de git ni de compte, seulement d’accès réseau à l’URL. Nécessite Claude Code v2.1.224 ou ultérieur. Épinglez chaque archive avec sha256 pour que Claude Code refuse un téléchargement modifié. Pour envoyer des identifiants avec le téléchargement, voir Authentifier les téléchargements d’archive.
• Un référentiel git public : Claude Code clone une source url ou git-subdir publique sur HTTPS sans identifiants quand l’entrée donne une URL https://. Pour une source github, ou une source git-subdir écrite comme owner/repo, les utilisateurs sans clé SSH GitHub définissent CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1.

​

Ce que la mise à jour automatique en arrière-plan fait avec les identifiants

• Distants SSH : une clé chargée dans ssh-agent authentifie la vérification.
• Distants HTTPS avec un identifiant stocké : un assistant qui peut fournir un identifiant stocké sans demander authentifie la vérification. Git Credential Manager, l’assistant Keychain macOS, et git-credential-store fonctionnent de cette façon une fois qu’ils détiennent un identifiant pour l’hôte.
• Distants HTTPS avec un assistant qui a besoin de demander : l’assistant ne peut pas répondre en arrière-plan. La mise à jour échoue silencieusement et le checkout existant reste en place, donc les plugins de l’utilisateur continuent à fonctionner à partir du dernier état synchronisé.

• Le checkout est à jour : Claude Code le laisse tel quel.
• La vérification trouve de nouveaux commits, ou échoue parce qu’elle ne peut pas atteindre ou s’authentifier au distant : Claude Code clone la marketplace à nouveau et remplace le checkout existant par le nouveau clone. Si ce clone échoue, le checkout existant reste en place. Le re-clone peut expirer sur les grands référentiels.

• Stocker un identifiant : se connecter d’abord à l’assistant d’identifiants pour qu’il détienne un identifiant pour l’hôte. Pour GitHub, exécutez gh auth login, puis gh auth setup-git.
• Garder le checkout en cas d’échec : si l’utilisateur définit CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1, Claude Code garde le checkout existant sans tenter le re-clone quand la vérification en arrière-plan ne peut pas atteindre ou s’authentifier au distant. Les plugins continuent à fonctionner à partir du dernier état synchronisé.

​

Déployer dans toute une entreprise

• Sources d’entrée qui n’ont pas besoin de compte git : Servir les utilisateurs qui n’ont pas de compte sur l’hôte git
• Un répertoire de plugins pré-rempli : Ensemencer les conteneurs et CI, qui sert aussi les utilisateurs qui n’ont pas de compte sur l’hôte git
• Paramètres de l’organisation claude.ai : Distribuer via les paramètres de l’organisation, où les identifiants git de vos utilisateurs ne sont pas impliqués

​

Tenir les utilisateurs à jour

​

Activer la mise à jour automatique

• Dites aux utilisateurs de l’activer : chaque utilisateur va à Marketplaces dans /plugin, sélectionne votre marketplace, et sélectionne Enable auto-update.
• Demandez à un administrateur de la définir : si un administrateur définit "autoUpdate": true sur l’entrée extraKnownMarketplaces de votre marketplace dans les paramètres gérés, elle est activée pour tout le monde qui reçoit ces paramètres. Voir Définir la politique de mise à jour.

​

Publier une nouvelle version

• Augmentez version à chaque version : les utilisateurs restent sur leur copie en cache jusqu’à ce que la chaîne change. Si vous définissez "version": "1.0.0" et poussez de nouveaux commits sans le modifier, les utilisateurs ne les reçoivent pas.
• Omettez version : les utilisateurs suivent vos commits à la place. Laissez version hors de plugin.json et de l’entrée de marketplace.

​

Garder les utilisateurs sur une version

• ref et sha sur l’entrée du plugin : ref nomme une branche ou une étiquette et sha nomme un commit pour une source github, url, ou git-subdir. Voir Sources de plugin.
• #<ref> sur la commande add : les utilisateurs qui ajoutent your-org/your-marketplace#stable obtiennent cette branche ou étiquette du catalogue. Pour deux lignes de version à la fois, voir Exécuter les canaux de version.
• Étiquettes <plugin>--v<version> : la plage de version d’une dépendance se résout par rapport à ces étiquettes. Voir Publier un plugin sur lequel d’autres dépendent.

​

Modifier la commande d’une source de commande

• Pas plus d’exécutions en arrière-plan : l’exécution une fois par session de la commande s’arrête pour cet utilisateur, donc la nouvelle sortie de l’outil ne les atteint pas.
• Une entrée dans l’onglet Erreurs /plugin : l’entrée affiche la nouvelle commande et la commande claude plugin update à exécuter.

​

Exécuter les canaux de version

{
  "name": "stable-tools",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "stable" } }
  ]
}

{
  "name": "latest-tools",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "latest" } }
  ]
}

​

Renommer ou supprimer un plugin

​

Migrer les utilisateurs avec une carte de renommages

{
  "name": "your-marketplace",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

• Entrée renommée : le plugin se charge sous son nouveau nom. claude plugin list et les détails du plugin sous /plugin affichent Renamed to "code-formatter" in the "your-marketplace" marketplace une fois, et Claude Code réécrit l’ancienne clé à la nouvelle dans enabledPlugins et pluginConfigs dans les portées de paramètres utilisateur, projet et local.
• Entrée null : l’ancienne clé est supprimée de ces portées et l’utilisateur voit Removed from the "your-marketplace" marketplace.
• Activé dans les paramètres gérés : le plugin se charge toujours sous son nouveau nom, mais Claude Code ne peut pas réécrire les paramètres gérés, donc l’avis se répète jusqu’à ce qu’un administrateur mette à jour enabledPlugins là.

​

Désinstaller les plugins supprimés des machines des utilisateurs

1. Compare ce que les utilisateurs ont installé à partir de votre marketplace par rapport aux entrées et à la carte renames, et traite tout plugin qui n’est ni listé ni renommé comme supprimé.
2. Désinstalle chaque plugin supprimé des portées utilisateur, projet et local. Les plugins que seuls les paramètres gérés ont installés restent en place.
3. Liste chaque plugin supprimé sous un en-tête Flagged dans /plugin avec le statut Removed from marketplace.

​

Authentifier les téléchargements d’archive

• La source url de la marketplace : la source url à partir de laquelle vous avez enregistré la marketplace, comme une entrée extraKnownMarketplaces.
• L’entrée du plugin : sur Claude Code v2.1.238 ou ultérieur, vous pouvez la définir sur l’entrée marketplace.json du plugin à la place, à côté de source.

​

Ajouter un headersHelper à une entrée de plugin

{
  "name": "my-plugin",
  "description": "Formatting commands for internal services",
  "strict": false,
  "source": {
    "source": "archive",
    "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"
  },
  "headersHelper": "/opt/bin/mint-registry-token.sh"
}

​

Écrire la commande headersHelper

• Texte de commande : au maximum 500 caractères ASCII imprimables, sans suite de quatre espaces ou plus.
• Sortie : imprimez un objet JSON de noms d’en-têtes et de valeurs de chaîne sur stdout, puis quittez 0 dans les 10 secondes.
• Shell et répertoire de travail : Claude Code exécute la commande via sh, ou via cmd.exe sur Windows. Le répertoire de travail est le répertoire de configuration, qui est ~/.claude ou CLAUDE_CONFIG_DIR. Donnez un chemin absolu ou une commande sur PATH, parce qu’un chemin relatif se résout par rapport à ce répertoire, pas au projet de l’utilisateur.
• Variables que Claude Code supprime : quand la commande est définie dans une entrée marketplace.json, ou dans le .claude/settings.json ou .claude/settings.local.json d’un projet, Claude Code supprime de l’environnement chaque variable dont le nom ressemble à un identifiant, par la même règle qu’elle applique à un headersHelper MCP. ANTHROPIC_API_KEY et MY_REGISTRY_TOKEN sont tous deux supprimés, donc faites en sorte que la commande lise son identifiant à partir d’un fichier ou d’un magasin d’identifiants. Cette suppression ne s’applique pas à une commande définie dans les paramètres utilisateur, un fichier --settings, ou les paramètres gérés.
• Variables que Claude Code définit : CLAUDE_CODE_MARKETPLACE_URL et CLAUDE_CODE_MARKETPLACE_NAME pour la commande d’une source url, et CLAUDE_CODE_PLUGIN_NAME et CLAUDE_CODE_PLUGIN_ARCHIVE_URL pour la commande d’une entrée. CLAUDE_CODE_MARKETPLACE_NAME n’est pas défini sur la première récupération après qu’un utilisateur ajoute une marketplace par URL, parce que cette récupération est ce qui fournit le nom.

{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

​

Quand Claude Code ignore une commande headersHelper ou supprime sa sortie

• La commande échoue : si la commande quitte non-zéro, s’exécute au-delà de 10 secondes, ou imprime autre chose qu’un objet JSON de valeurs de chaîne, la récupération ou le téléchargement pour lequel la commande a été exécutée ne se produit pas.
• L’URL de marketplace ne commence pas par https:// : la commande de cette source url ne s’exécute pas, et les demandes ne portent que les en-têtes listés dans son champ headers.
• La redirection quitte l’origine : quand un téléchargement est redirigé hors de l’origine de l’URL d’archive, la demande redirigée ne porte pas de valeurs headers ou de sortie de commande de la source url de marketplace ou de l’entrée de plugin.
• L’entrée définit un en-tête de routage ou d’identité : Claude Code supprime les noms de routage de demande et d’identité de client comme Host, Cookie, et X-Forwarded-* de headers et de la sortie de commande d’une entrée, et garde les noms d’authentification comme Authorization. Chaque entrée marketplace.json est filtrée de cette façon. Pour une entrée de plugin en ligne dans les paramètres, voir extraKnownMarketplaces.
• La commande est définie dans les paramètres d’un répertoire --add-dir : la commande est ignorée, sur une source url et sur une entrée de plugin en ligne de même, et seuls les headers de ce fichier sont envoyés.
• Les paramètres gérés bloquent la commande : définir disableCommandPluginSources à true bloque les commandes headersHelper, et allowManagedHooksOnly les bloque aussi sauf si disableCommandPluginSources est explicitement false. Sous l’un ou l’autre bloc, Claude Code exécute toujours la commande pour une marketplace que les paramètres gérés eux-mêmes déclarent.

​

Comment les utilisateurs acceptent une commande headersHelper

​

Installations et mises à jour qui refusent une commande au lieu de demander

• Installation de plusieurs plugins à la fois, à partir d’une suggestion de plugin, ou en tant que dépendance d’un autre plugin : Claude Code refuse le plugin qui a la commande et dirige l’utilisateur à la vue propre de ce plugin dans /plugin. Les autres plugins dans une installation en masse s’installent toujours. Un plugin qui dépend du plugin refusé échoue à s’installer jusqu’à ce que l’utilisateur installe le plugin refusé par lui-même.
• Mise à jour automatique en arrière-plan, ou démarrage de session pour un plugin dont l’archive n’a jamais été téléchargée : Claude Code énumère le plugin dans l’onglet Erreurs /plugin pour que l’utilisateur sache l’installer ou le mettre à jour lui-même.

​

Quand la commande d’une source url de marketplace s’exécute

​

Dépendre d’autres plugins et les recommander

• Plages de version : une dépendance peut porter une plage semver.
• Dépendances entre marketplaces : une dépendance d’une autre marketplace s’installe uniquement quand votre marketplace énumère cette marketplace dans allowCrossMarketplaceDependenciesOn.

​

Contourner ce qu’une marketplace ne peut pas faire

• Restreindre ce que d’autres utilisateurs installent : la liste d’autorisation de marketplace est un paramètre géré, strictKnownMarketplaces. Voir Restreindre ce que les utilisateurs peuvent installer.
• Installer ou activer un plugin sans que l’utilisateur le demande : aucun champ d’entrée n’installe un plugin. Les enabledPlugins gérés le font pour une flotte ; voir Pré-installer et exiger des plugins.
• Afficher des entrées différentes à différents utilisateurs : les entrées ne portent pas de champ d’audience, et chaque utilisateur qui ajoute la marketplace voit le catalogue entier. Hébergez des marketplaces séparées pour des audiences séparées.
• Marquer un plugin comme obsolète : il n’y a pas d’état d’obsolescence. L’option est de supprimer l’entrée, de mapper son nom à null dans renames, et éventuellement de définir forceRemoveDeletedPlugins.
• Activer la mise à jour automatique pour vos utilisateurs : chaque utilisateur l’active sous Marketplaces dans /plugin, ou un administrateur définit autoUpdate dans les paramètres gérés. Voir Activer la mise à jour automatique.
• Porter les identifiants git : aucun champ de marketplace ne détient un jeton git. L’accès à une marketplace ou un plugin hébergé sur git suit la configuration git de l’utilisateur, selon Accorder l’accès à une marketplace privée. Pour les sources archive, une entrée peut définir headers ou headersHelper à la place.

​

Étapes suivantes

• Référence de marketplace : champs marketplace.json, types de source, et messages de validation
• Gérer les plugins pour votre organisation : exiger, restreindre, ou ensemencer votre marketplace sur les machines de votre organisation
• Dépendances de plugin : étiqueter les versions pour que les plugins qui dépendent du vôtre puissent résoudre les versions
• Dépanner les plugins : les erreurs que vos utilisateurs voient lors de l’ajout ou de la mise à jour à partir de votre marketplace