Mergerie
Sommaire

Les plugins de Mergerie — en 5 minutes

Cette page est générée depuis docs/plugins/README.md · Modifier cette page sur GitLab

Un plugin est un dossier avec un plugin.json et un index.js qui exporte activate(ctx) et deactivate(). Il ajoute à Mergerie ce que le cœur ne fait pas — un onglet, des actions sur les merge requests, une tâche de fond, une intégration — sans toucher au code du cœur : tout ce qu'il peut faire passe par le ctx, une liste fermée de primitives (réglages, secrets, tables, routes, tâches, événements, écran…). Un plugin embarqué dans le dépôt (plugins/hello) et un plugin que vous installez chez vous ont exactement les mêmes droits.

Un abonné ne doit pas attendre. Le bus appelle les abonnés d'un événement l'un après l'autre et en attend chacun (30 s au plus) : un travail long — un processus, un navigateur, un appel réseau lent — se met en file et rend la main (voir jenkins-teams-notify), son issue va dans le journal du plugin.

Installer hello, l'activer, modifier un réglage

hello est livré avec Mergerie, désactivé d'office. Il journalise chaque événement du cœur qu'il reçoit et expose un réglage.

  1. Ouvrez Réglages → Plugins. La liste montre chaque plugin : version, état, permissions, dépendances, événements écoutés et émis.
  2. Sur Hello, cliquez Activer. La page se recharge — Mergerie ne redémarre pas — et un onglet Hello apparaît dans la barre (replié d'office : Réglages → Général → Menus pour l'afficher).
  3. Toujours dans Réglages → Plugins, le formulaire de Hello (généré depuis son settingsSchema) porte un champ Salutation. Changez-le, Enregistrer : GET /api/plugins/hello/ping répond avec la nouvelle valeur, et l'onglet l'affiche.
  4. Lancez une session, une review, une vérification : l'onglet Hello liste les événements reçus (session.finished, review.completed…), avec leur payload et sa version.
  5. Désactiver retire l'onglet, les routes, les abonnements et la tâche de fond ; les données du plugin (sa table, son réglage) restent. Activer les retrouve.

Installer un plugin tiers

Trois voies, aucune ne redémarre Mergerie :

  • Un dossier déposé dans <dataDir>/plugins/<nom>/ (par défaut ~/.mergerie/data/plugins/), puis Rescanner dans Réglages → Plugins.
  • « Installer un plugin » → dossier local : le manifeste est vérifié, le dossier copié.
  • « Installer un plugin » → adresse git : clone sans shell (branche ou tag optionnels), manifeste vérifié avant la copie.

Un plugin tiers est désactivé après installation, tourne dans son propre worker (un plugin qui plante ne tue jamais le serveur), et ses permissions s'affichent avant qu'on l'active — exec (lancer des programmes) déclenche un avertissement explicite. Désinstaller supprime le dossier et propose de garder ou de supprimer ses données. Il n'y a ni registre central ni téléchargement automatique.

Mettre à jour : installé depuis git (ou depuis un dossier), un plugin garde son adresse d'installation, et le bouton « Mettre à jour » de sa carte la rejoue — il clone d'abord (un échec réseau laisse le plugin intact), puis le désactive, remplace son dossier et le réactive s'il l'était. Ses données, ses réglages et ses secrets ne bougent pas ; les migrations de tables en attente se jouent à l'activation. Augmentez version dans plugin.json avant de publier, c'est ce que l'écran affiche (1.0.0 → 1.0.1). Un plugin installé avant que l'adresse soit gardée n'a pas le bouton : l'installer une fois de plus depuis git suffit. Un plugin embarqué se met à jour avec Mergerie.

Lire ensuite

PagePour
GETTING-STARTED.mdcréer son premier plugin avec le générateur, le tester sans Mergerie, l'installer
API.mdla référence du ctx, primitive par primitive, avec permission, signature, erreurs
EVENTS.mdchaque événement, quand il est émis, son payload et sa version
UI.mdce qu'un plugin ajoute à l'écran et le kit window.mergerie
DATA.mdtables, préfixe, migrations, classement P/L/C, rétention
SECURITY.mdle modèle de confiance, ce qu'un plugin ne peut pas faire
PUBLISHING.mdnommer, documenter, publier (licence AGPL), être listé
MIGRATION.mdcomment l'apiVersion évolue, et ce que le cœur garantit
COMMUNITY.mdles plugins connus

Pour l'histoire du chantier : JENKINS-INVENTORY.md (l'inventaire qui a dimensionné l'API) et PLUGIN-CANDIDATES.md (Liens, Docker — fait, en plugin tiers — et Git, les prochains).

Dans cette section

  1. Créer son premier pluginPrérequis : Node 22, et un clone de Mergerie (pour le SDK, tant qu'il n'est pas publié sur npm : sdk/ du dépôt est @mergerie/plugin-sdk).
  2. Référence de l’API du ctxGénéré depuis sdk/contract.js (API 1) par sdk/scripts/generer-docs-api.js — ne pas éditer à la main. Les exemples cités sont des fichiers de…
  3. Les événementsGénéré depuis sdk/contract.js (API 1) par sdk/scripts/generer-docs-events.js — ne pas éditer à la main.
  4. L'écran d'un pluginLe front de Mergerie est une seule portée globale, sans build ni modules : index.html liste ses <script> et <link> dans l'ordre, et npm run check garantit…
  5. Les données d'un pluginUn plugin lit et écrit uniquement des tables nommées plugin_<nom>_* (le nom avec ses tirets remplacés par _ : plugin_mon_plugin_note). ctx.db.prepare,…
  6. Sécurité des pluginsMergerie est un outil local qui tient les jetons de votre forge, de Jira, de vos plugins, et qui pilote un agent IA sur votre machine. Un plugin est du code…
  7. Publier un pluginLe name du manifeste est en kebab-case (a-z, 0-9, tirets), unique, et c'est le nom du dossier : <dataDir>/plugins/<name>/.
  8. L'API des plugins et ses versionsL'apiVersion courante est 1 (sdk/contract.js → API_VERSION). Elle couvre :
  9. Les plugins connusPour y figurer : PUBLISHING.md. La liste n'est pas un registre — rien n'est téléchargé automatiquement, et Mergerie ne vérifie pas le code des plugins qui y…