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.
- Ouvrez Réglages → Plugins. La liste montre chaque plugin : version, état, permissions, dépendances, événements écoutés et émis.
- 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).
- 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/pingrépond avec la nouvelle valeur, et l'onglet l'affiche. - 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. - 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
| Page | Pour |
|---|---|
| GETTING-STARTED.md | créer son premier plugin avec le générateur, le tester sans Mergerie, l'installer |
| API.md | la référence du ctx, primitive par primitive, avec permission, signature, erreurs |
| EVENTS.md | chaque événement, quand il est émis, son payload et sa version |
| UI.md | ce qu'un plugin ajoute à l'écran et le kit window.mergerie |
| DATA.md | tables, préfixe, migrations, classement P/L/C, rétention |
| SECURITY.md | le modèle de confiance, ce qu'un plugin ne peut pas faire |
| PUBLISHING.md | nommer, documenter, publier (licence AGPL), être listé |
| MIGRATION.md | comment l'apiVersion évolue, et ce que le cœur garantit |
| COMMUNITY.md | les 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
- 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).
- 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…
- Les événementsGénéré depuis sdk/contract.js (API 1) par sdk/scripts/generer-docs-events.js — ne pas éditer à la main.
- 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…
- 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,…
- 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…
- 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>/.
- L'API des plugins et ses versionsL'apiVersion courante est 1 (sdk/contract.js → API_VERSION). Elle couvre :
- 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…