Importer et synchroniser des plugins depuis GitHub

Vous pouvez importer des plugins depuis GitHub dans votre espace de travail et les tenir à jour au fil des modifications du dépôt. Une marketplace est un fichier JSON qui répertorie les plugins à importer.

Avant de commencer

Vous devez être administrateur de l’espace de travail. Utilisez un compte GitHub qui dispose d’un accès en lecture au dépôt de la marketplace et à tous les dépôts qu’elle référence. Les dépôts GitHub publics et privés sont pris en charge. Avant l’importation, obtenez les approbations d’accès exigées par votre organisation GitHub.

Examinez le dépôt avant de l’importer. Les paramètres par défaut déterminent quels plugins les membres peuvent utiliser :

• Les nouveaux plugins ont le statut Disponible et les membres peuvent les installer. Si une authentification est requise, les membres s’authentifient lors de l’installation du plugin.
• L’importation traite toutes les entrées valides. Les nouvelles marketplaces se synchronisent automatiquement chaque jour et ajoutent les nouveaux plugins du dépôt.

Ce guide explique comment importer des plugins dans un espace de travail. Pour les clients locaux, consultez Configurer les marketplaces de plugins et les paramètres par défaut pour connaître les paramètres gérés dans le cloud ou définis dans le fichier config.toml du système. Pour un projet en particulier, consultez Activer ou désactiver un plugin pour un dépôt.

Configurer la synchronisation d’une marketplace

1. Ouvrez Admin > 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 préciser de branche ni de dossier.
3. Si la marketplace se trouve dans un sous-répertoire, saisissez ce répertoire dans Chemin. Par exemple, indiquez team-tools pour team-tools/.agents/plugins/marketplace.json. Laissez le champ Chemin vide pour utiliser la racine du dépôt. Ne saisissez pas le nom du fichier manifeste.
4. Si nécessaire, renseignez le champ Branche, tag ou commit. Laissez-le vide pour utiliser la branche par défaut du dépôt. Une branche permet de recevoir les mises à jour ultérieures. Si vous indiquez un commit précis, vous conservez la version sélectionnée.
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 marketplaces de très grande taille. Les synchronisations quotidiennes suivantes prennent généralement quelques minutes.
6. Consultez les Résultats de l’importation, puis ouvrez chaque plugin importé pour configurer sa politique d’installation et les applications dont il a besoin.

Formats pris en charge

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

Les entrées d’une marketplace peuvent référencer 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.

Dans une marketplace Codex, utilisez des chemins locaux pour les plugins qui se trouvent 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 sélectionnée pour la marketplace, et non à .agents/plugins/.

Une marketplace compatible avec Claude peut indiquer le chemin de chaque plugin local sous forme de chaîne de caractères :

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

Les entrées d’une marketplace Codex acceptent également 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 du dépôt. Par exemple :

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

Pour une source Git, vous pouvez préciser une référence avec ref ou un commit avec son sha complet de 40 caractères. Le compte GitHub utilisé pour autoriser l’accès doit pouvoir lire tous les dépôts référencés. Pour le moment, seuls les dépôts GitHub peuvent être importés dans un espace de travail.

Configurer les accès dans l’espace de travail

Configurez les paramètres d’installation et d’authentification de chaque plugin dans votre espace de travail. L’importation et la synchronisation ne reprennent pas ces paramètres depuis le dépôt. Les valeurs possibles comprennent AVAILABLE, INSTALLED_BY_DEFAULT, NOT_AVAILABLE, ON_INSTALL et ON_USE. L’espace de travail conserve ses paramètres lorsque vous synchronisez une mise à jour ou transférez la gestion d’un plugin vers GitHub.

Dans Politique d’installation, choisissez Disponible ou Installé pour chaque rôle éligible. Activez également les applications dont le plugin a besoin et vérifiez que les membres ont accès au service connecté. L’importation d’un plugin n’accorde pas aux membres l’accès aux applications et ne connecte pas leurs comptes. Consultez Paramètres des plugins pour choisir les paramètres d’accès et les actions autorisées.

Transférer la gestion d’un plugin existant vers 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 Admin > Plugins et copiez l’identifiant qui suit /plugins/ dans son URL. Placez pluginId au même niveau que name et source dans l’entrée de la marketplace. Le plugin existant doit se trouver dans le même espace de travail et la valeur de name dans l’entrée doit correspondre à son nom.

Utilisez cette méthode pour transférer la gestion d’un plugin de l’espace de travail vers GitHub s’il n’y est pas déjà géré. Le plugin conserve son identifiant, ses paramètres de partage et ses paramètres dans l’espace de travail. Les mises à jour suivantes proviennent de GitHub. Vous ne pouvez donc plus remplacer le plugin en important une archive. Cette méthode ne peut pas servir pour un plugin déjà géré depuis une autre source GitHub.

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

Les plugins portant la mention Application de bureau uniquement ne peuvent pas s’exécuter dans ChatGPT sur le Web. Les plugins importés peuvent recevoir cette mention s’ils déclarent des serveurs MCP, y compris des serveurs accessibles via des URL HTTPS distantes. L’ajout d’une référence à .app.json ne suffit pas à supprimer cette mention.

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

Ajoutez .app.json à la racine du plugin. Le nom du fichier commence par un point. Le nom 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 de type 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 si 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 le manifeste complet de 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 l’arborescence suivante :

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

Ce fichier référence une application existante. Il ne crée aucune application et n’accorde aucun accès. Rendez l’application accessible aux rôles qui en ont besoin et demandez aux membres de s’authentifier si nécessaire. Les autorisations de l’application, les actions permises et les droits d’accès au service connecté continuent de s’appliquer.

Tenir les plugins à jour

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

La synchronisation peut ajouter de nouveaux plugins depuis la marketplace et mettre à jour les plugins existants. Examinez les modifications du dépôt avant de les fusionner, car la synchronisation automatique importe aussi les nouveaux plugins.

Après chaque synchronisation, vérifiez son statut et consultez le rapport enregistré. Même si la synchronisation est terminée, certains plugins peuvent présenter des erreurs. Si une mise à jour est invalide, le plugin existant conserve sa dernière version fonctionnelle. Corrigez le problème dans GitHub, puis sélectionnez Synchroniser maintenant pour réessayer.

Si vous supprimez l’entrée d’un plugin de la marketplace, sa copie reste dans l’espace de travail avec la mention Absent de la source. En revanche, si vous supprimez la marketplace dans ChatGPT, tous les plugins importés depuis cette marketplace sont également supprimés.

Rétablir ou modifier l’accès à GitHub

La synchronisation d’une marketplace utilise la connexion GitHub de l’administrateur qui l’a importée.

Pour rétablir la connexion, vérifiez d’abord que le compte GitHub de cet administrateur dispose toujours d’un accès en lecture au dépôt de la marketplace et à tous les dépôts qu’elle référence. Cet administrateur doit ensuite ouvrir le plugin GitHub dans ChatGPT et reconnecter son compte.

Pour changer de propriétaire, le nouvel administrateur de l’espace de travail doit réimporter la marketplace depuis Admin > Plugins > Ajouter > Importer une marketplace. Utilisez les mêmes valeurs pour Source, Chemin et Branche, tag ou commit. Les prochaines synchronisations utiliseront la connexion GitHub du nouvel administrateur.

Conservez la marketplace lors de la reconnexion ou du changement de propriétaire. Sa suppression entraîne également celle des plugins importés depuis cette marketplace.