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 places de marché directement sur les clients locaux via config.toml administré dans le cloud ou au niveau du système, voir Configurer les places de marché de plugins et les paramètres par défaut. Pour activer ou désactiver des plugins pour un projet précis, voir Activer ou désactiver un plugin pour un dépôt.

Utilisez un compte GitHub capable de lire le dépôt de la marketplace ainsi que 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 requises par l’organisation GitHub pour accéder à votre dépôt.

Examinez le contenu du dépôt avant de l’importer. Les nouveaux plugins utilisent initialement l’installation Disponible et l’authentification lors de l’installation. La synchronisation quotidienne automatique est activée pour les nouvelles marketplaces. L’importation traite toutes les entrées valides, et les synchronisations ultérieures ajoutent automatiquement les nouveaux plugins présents dans le dépôt.

Configurer la synchronisation d’une marketplace

1. Ouvrez Administration > Plugins, puis 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. Vous pouvez également saisir une Branche, un tag ou un commit. Laissez ce champ vide pour utiliser la branche par défaut du dépôt. Utilisez une branche pour recevoir les prochains commits ; un commit fixe reste à cette révision.
5. Sélectionnez Importer la marketplace et autorisez l’accès à GitHub lorsque vous y êtes invité. L’importation initiale peut prendre jusqu’à une heure pour les marketplaces très volumineuses. Les synchronisations quotidiennes suivantes prennent généralement quelques minutes.
6. Consultez les Résultats de l’importation, puis ouvrez chaque plugin importé afin de configurer sa politique d’installation et les applications requises.

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

Formats pris en charge

Le répertoire sélectionné doit contenir l’un des fichiers suivants :

Dans une marketplace, les entrées peuvent référencer des plugins natifs avec .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 chemin pour chaque plugin local :

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

Les entrées d’une 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 placé 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"
  }
}

Les sources Git peuvent sélectionner un ref ou un sha de commit complet de 40 caractères. Le compte GitHub qui accorde l’autorisation doit pouvoir lire chaque dépôt référencé. L’importation dans un espace de travail ne prend actuellement en charge que les dépôts GitHub.

Configurer l’accès à 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 sous gestion GitHub conserve ses politiques d’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 en savoir plus sur les contrôles des rôles, des applications et des actions.

Placer un plugin existant sous gestion GitHub

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’ID qui suit /admin/plugins/ dans son URL. Placez pluginId à côté de name et source dans l’entrée de la marketplace. Le plugin existant doit se trouver dans le même espace de travail.

Cette opération place sous gestion GitHub un plugin d’espace de travail téléversé ou non géré par ailleurs. Le plugin conserve son ID, ses paramètres de partage et ses politiques d’espace de travail. Les futures mises à jour proviendront de GitHub ; les téléversements d’archives ne pourront plus remplacer le plugin géré. Un plugin déjà géré par une autre source GitHub ne peut pas être repris de cette manière.

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

Tout plugin importé qui déclare des MCP servers 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, telles que les déclarations de serveur intégrées.

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

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

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

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

La clé team-tools nomme la référence dans ce fichier. Définissez required sur true lorsque le plugin dépend de l’application. Vous pouvez ajouter d’autres 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 les fichiers selon cette arborescence :

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 accessible aux rôles concernés, et les membres doivent effectuer toute authentification requise. Les autorisations, les contrôles des actions et l’accès au service existants de l’application continuent de s’appliquer.

Maintenir 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 apportées au dépôt avant de les fusionner, car la synchronisation automatique importera tous les nouveaux plugins.

Après une synchronisation, consultez le statut et le rapport enregistré. Terminée — N erreurs signifie que l’opération est arrivée à son terme, mais que certains plugins n’ont pas pu être traités. Si la mise à jour d’un plugin existant n’est pas valide, 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. Elle porte alors la mention N’est plus dans la source. La suppression de la marketplace dans ChatGPT supprime tous les plugins importés depuis celle-ci.

Reconnecter ou modifier l’accès à GitHub

Pour reconnecter 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 ayant initialement importé la marketplace doit ensuite ouvrir le plugin GitHub dans ChatGPT et reconnecter son compte, car la synchronisation de la marketplace utilise la connexion GitHub de cet administrateur.

Pour transférer la marketplace à 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 en utilisant les mêmes valeurs pour Source, Chemin et Branche, tag ou commit. Les prochaines synchronisations utiliseront sa connexion GitHub.

Ne supprimez pas la marketplace dans le seul but de la reconnecter ou d’en changer le propriétaire : sa suppression entraîne également celle des plugins importés depuis cette marketplace.