Gestion des plugins

Avant de commencer

Les administrateurs de l’espace de travail peuvent importer une marketplace de plugins depuis GitHub et maintenir ses plugins à jour à partir du dépôt. Une marketplace est un catalogue JSON qui répertorie les plugins à importer.

Cette page traite de l’importation et de la synchronisation dans l’espace de travail. Pour configurer des marketplaces directement sur les clients locaux via un fichier config.toml géré dans le cloud ou au niveau du système, consultez Configurez les marketplaces de plugins et les paramètres par défaut. Pour activer ou désactiver des plugins pour un projet donné, consultez Activez ou désactivez un plugin pour un dépôt.

Utilisez un compte GitHub disposant d’un accès en lecture au dépôt de la marketplace et à tous les autres dépôts auxquels il fait référence. Les dépôts GitHub publics et privés sont pris en charge. Avant l’importation, obtenez toutes les approbations de l’organisation GitHub nécessaires pour accéder aux dépôts.

Examinez le contenu du dépôt avant l’importation. Les nouveaux plugins ont initialement la politique d’installation Disponible , avec une authentification à l’installation. La synchronisation automatique quotidienne est activée pour les nouvelles marketplaces. L’importation traite toutes les entrées valides, et les synchronisations suivantes ajoutent automatiquement tout nouveau plugin présent dans le dépôt.

Configurez la synchronisation d’une marketplace

1. Ouvrez Administration > Plugins et sélectionnez Ajouter > Importer une marketplace.
2. Dans Source, saisissez l’URL du dépôt, par exemple https://github.com/example/team-plugins. Utilisez uniquement l’URL du dépôt, sans URL de branche ni de dossier.
3. Si la marketplace se trouve dans un sous-répertoire, saisissez ce répertoire dans Chemin. Par exemple, utilisez team-tools pour team-tools/.agents/plugins/marketplace.json. Laissez Chemin vide pour utiliser la racine du dépôt. Ne saisissez pas le nom du fichier manifeste.
4. Si vous le souhaitez, renseignez le champ Branche, tag ou commit. Laissez ce champ vide pour utiliser la branche par défaut du dépôt. Utilisez une branche pour recevoir les futurs commits ; si vous indiquez un commit précis, la version restera figée sur celui-ci.
5. Sélectionnez Importer une marketplace et autorisez l’accès à GitHub lorsque vous y êtes invité. L’importation initiale peut prendre jusqu’à une heure pour les très grandes marketplaces. Les synchronisations quotidiennes suivantes prennent généralement quelques minutes.
6. Examinez les Résultats de l’importation, puis ouvrez chaque plugin importé pour configurer sa politique d’installation et les éventuelles applications requises.

Pour demander une mise à jour sans attendre la synchronisation quotidienne, ouvrez la marketplace dans Administration > Plugins > Marketplaces et sélectionnez Synchroniser maintenant.

Formats pris en charge

Le répertoire sélectionné doit contenir l’un de ces fichiers :

Dans une marketplace, les entrées peuvent faire référence à des plugins natifs dotés d’un fichier .codex-plugin/plugin.json, à des plugins compatibles avec Claude, à des packages Agent Plugins 1.0 ou à des packages de skills pris en charge.

Pour une marketplace Codex, utilisez des chemins locaux pour les plugins situés dans le même dépôt :

{
  "name": "team-plugins",
  "interface": {
    "displayName": "Team plugins"
  },
  "plugins": [
    {
      "name": "team-tools",
      "source": {
        "source": "local",
        "path": "./plugins/team-tools"
      }
    }
  ]
}

Le chemin est relatif à la racine de la marketplace sélectionnée, et non à .agents/plugins/.

Une marketplace compatible avec Claude peut utiliser une chaîne de caractères représentant le chemin de chaque plugin local :

{
  "name": "team-plugins",
  "plugins": [
    {
      "name": "team-tools",
      "source": "./plugins/team-tools"
    }
  ]
}

Les entrées de marketplace Codex prennent également en charge source: "url" pour un plugin situé à la racine d’un dépôt GitHub et source: "git-subdir" pour un plugin situé dans un sous-répertoire GitHub. Par exemple :

{
  "name": "team-tools",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/example/team-tools.git",
    "path": "./plugins/team-tools",
    "ref": "main"
  }
}

Pour les sources Git, vous pouvez sélectionner une ref ou le sha complet d’un commit, composé de 40 caractères. Le compte GitHub qui autorise l’accès doit disposer d’un accès en lecture à chaque dépôt référencé. L’importation dans l’espace de travail ne prend actuellement en charge que les dépôts GitHub.

Configurez l’accès dans l’espace de travail

L’importation et la synchronisation depuis GitHub n’appliquent pas les politiques d’installation ou d’authentification du dépôt, notamment AVAILABLE, INSTALLED_BY_DEFAULT, NOT_AVAILABLE, ON_INSTALL et ON_USE. Les administrateurs de l’espace de travail configurent ces paramètres pour chaque plugin. La synchronisation d’une mise à jour ou le passage d’un plugin existant à une gestion via GitHub conserve les politiques qui lui sont appliquées dans l’espace de travail.

Utilisez Politique d’installation pour choisir Disponible ou Installé pour chaque rôle éligible. Les applications requises doivent également être activées, et les membres doivent avoir accès au service connecté. L’importation d’un plugin n’accorde pas l’accès aux applications et ne connecte pas les comptes des membres. Consultez Contrôles des plugins pour connaître les contrôles des rôles, des applications et des actions.

Passez à une gestion via GitHub pour un plugin existant

Ajoutez pluginId à l’entrée du plugin existant dans la marketplace :

{
  "name": "team-tools",
  "pluginId": "plugin_0123456789abcdef0123456789abcdef",
  "source": {
    "source": "local",
    "path": "./plugins/team-tools"
  }
}

Ouvrez le plugin depuis Administration > Plugins et copiez l’identifiant situé après /admin/plugins/ dans son URL. Placez pluginId à côté de name et de source dans l’entrée de la marketplace. Le plugin existant doit se trouver dans le même espace de travail.

Cette opération permet de gérer via GitHub un plugin de l’espace de travail téléversé ou non géré par une source. Le plugin conserve son identifiant, ses paramètres de partage et ses politiques d’espace de travail. Les futures mises à jour proviennent de GitHub ; le téléversement d’archives ne permet plus de remplacer le plugin ainsi géré. Cette méthode ne permet pas de reprendre la gestion d’un plugin déjà géré par une autre source GitHub.

Plugins réservés à l’application de bureau

Tout plugin importé qui déclare des serveurs MCP dans mcp.json ou .mcp.json porte la mention Application de bureau uniquement et fonctionne uniquement dans l’application de bureau ChatGPT. Cela inclut les serveurs qui utilisent une URL HTTPS distante. La même restriction s’applique aux autres formes de configuration MCP prises en charge, comme les déclarations de serveurs intégrées directement à la configuration.

Référencez une application existante avec .app.json

Ajoutez .app.json à la racine du plugin. Le nom du fichier commence par un point ; app.json, sans le point, n’est pas pris en charge.

{
  "apps": {
    "team-tools": {
      "id": "asdk_app_example",
      "required": true
    }
  }
}

Remplacez asdk_app_example par l’identifiant de l’application existante. Les identifiants d’application pris en charge commencent par asdk_app_, connector_ ou templated_apps_. Utilisez l’identifiant de l’application, et non un identifiant plugin_.... Par exemple, une URL de plugin contenant plugin_asdk_app_example correspond à l’application asdk_app_example.

La clé team-tools donne un nom à la référence dans ce fichier. Définissez required sur true lorsque le plugin dépend de l’application. Vous pouvez ajouter des entrées pour référencer d’autres applications existantes.

Pour un plugin natif, définissez apps sur ./.app.json dans .codex-plugin/plugin.json. Voici un manifeste complet pour cet exemple :

{
  "name": "team-tools",
  "version": "1.0.0",
  "description": "Use the team's approved tools.",
  "author": {
    "name": "Example team"
  },
  "apps": "./.app.json",
  "interface": {
    "displayName": "Team tools",
    "shortDescription": "Use approved team tools",
    "longDescription": "Connect to the team's existing app.",
    "developerName": "Example team",
    "category": "Productivity",
    "capabilities": ["Read"]
  }
}

Conservez cette arborescence de fichiers :

team-plugins/
├── .agents/plugins/marketplace.json
└── plugins/team-tools/
    ├── .codex-plugin/plugin.json
    └── .app.json

La référence ne crée pas d’application et n’accorde aucune autorisation. Les administrateurs doivent rendre l’application disponible pour les rôles concernés, et les membres doivent effectuer toute authentification requise. Les autorisations de l’application, les contrôles des actions et les conditions d’accès au service existants continuent de s’appliquer.

Maintenez les plugins à jour

Les nouvelles marketplaces recherchent des mises à jour chaque jour. Ouvrez Administration > Plugins > Marketplaces, sélectionnez la marketplace, puis choisissez Synchroniser maintenant pour demander une mise à jour sans attendre la synchronisation automatique.

La synchronisation peut ajouter de nouvelles entrées de marketplace et mettre à jour les plugins existants. Examinez les modifications du dépôt avant de les fusionner, car la synchronisation automatique importera tout nouveau plugin.

Après une synchronisation, examinez son état et le rapport enregistré. Terminé — N erreurs signifie que le traitement est terminé, mais que certains plugins n’ont pas pu être traités. Si une mise à jour d’un plugin existant est invalide, sa dernière version fonctionnelle est conservée. Corrigez le problème signalé dans GitHub, puis sélectionnez Synchroniser maintenant pour réessayer.

La suppression d’une entrée du dépôt ne supprime pas sa copie importée dans l’espace de travail. Celle-ci porte la mention N’est plus dans la source. La suppression de la marketplace dans ChatGPT supprime tous les plugins qui en ont été importés.

Rétablissez ou modifiez l’accès à GitHub

Pour rétablir l’accès à GitHub, vérifiez d’abord que le compte GitHub utilisé pour l’importation a toujours accès au dépôt et aux éventuels dépôts référencés. L’administrateur qui a initialement importé la marketplace doit ensuite ouvrir le plugin GitHub dans ChatGPT et reconnecter son compte, car la synchronisation de la marketplace utilise sa connexion GitHub.

Pour transférer la propriété à un nouveau propriétaire, le nouvel administrateur de l’espace de travail doit ouvrir Administration > Plugins > Ajouter > Importer une marketplace et importer la même marketplace avec les mêmes valeurs pour Source, Chemin et Branche, tag ou commit . Les synchronisations suivantes utiliseront sa connexion GitHub.

Ne supprimez pas la marketplace simplement pour la reconnecter ou en changer le propriétaire : cette suppression efface également les plugins qui en ont été importés.