Mergerie plugins — in 5 minutes
This page is generated from docs/plugins/en/README.md · Edit this page on GitLab
A plugin is a folder with a plugin.json and an index.js exporting activate(ctx) and deactivate(). It adds to Mergerie what the core does not do — a tab, actions on merge requests, a background task, an integration — without touching the core's code: everything it can do goes through the ctx, a closed list of primitives (settings, secrets, tables, routes, tasks, events, screen…). A plugin shipped in the repository (plugins/hello) and a plugin you install yourself have exactly the same rights.
A subscriber must not wait. The bus calls an event's subscribers one after the other and waits for each (30 s at most): long work — a process, a browser, a slow network call — goes into a queue and returns at once (see
jenkins-teams-notify); its outcome goes to the plugin's own log.
Install hello, enable it, change a setting
hello ships with Mergerie, disabled by default. It logs every core event it receives and exposes one setting.
- Open Settings → Plugins. The list shows every plugin: version, state, permissions, dependencies, events listened to and emitted.
- On Hello, click Enable. The page reloads — Mergerie does not restart — and a Hello tab appears in the bar (folded by default: Settings → General → Menus to show it).
- Still in Settings → Plugins, Hello's form (generated from its
settingsSchema) has a Greeting field. Change it, Save:GET /api/plugins/hello/pinganswers with the new value, and the tab shows it. - Start a session, a review, a verification: the Hello tab lists the events received (
session.finished,review.completed…), with their payload and its version. - Disable removes the tab, the routes, the subscriptions and the background task; the plugin's data (its table, its setting) stays. Enable brings everything back.
Install a third-party plugin
Three ways, none of which restarts Mergerie:
- A folder dropped into
<dataDir>/plugins/<name>/(by default~/.mergerie/data/plugins/), then Rescan in Settings → Plugins. - "Install a plugin" → local folder: the manifest is checked, the folder copied.
- "Install a plugin" → git address: clone without a shell (optional branch or tag), manifest checked before copying.
A third-party plugin is disabled after installation, runs in its own worker (a crashing plugin never kills the server), and its permissions are shown before you enable it — exec (running programs) triggers an explicit warning. Uninstall deletes the folder and offers to keep or delete its data. There is no central registry and no automatic download.
Updating: installed from git (or from a folder), a plugin keeps its install address, and the "Update" button on its card replays it — it clones first (a network failure leaves the plugin untouched), then disables it, replaces its folder and enables it again if it was. Its data, settings and secrets are not touched; pending table migrations run at activation. Raise version in plugin.json before publishing: that is what the screen shows (1.0.0 → 1.0.1). A plugin installed before the address was kept has no button: installing it once more from git is enough. A built-in plugin is updated with Mergerie.
Read next
| Page | For |
|---|---|
| GETTING-STARTED.md | create your first plugin with the generator, test it without Mergerie, install it |
| API.md | the ctx reference, primitive by primitive, with permission, signature, errors |
| EVENTS.md | every event, when it is emitted, its payload and version |
| UI.md | what a plugin adds to the screen and the window.mergerie kit |
| DATA.md | tables, prefix, migrations, P/L/C classification, retention |
| SECURITY.md | the trust model, what a plugin cannot do |
| PUBLISHING.md | naming, documenting, publishing (AGPL licence), getting listed |
| MIGRATION.md | how apiVersion evolves, and what the core guarantees |
| COMMUNITY.md | known plugins |
For the history of the work: ../JENKINS-INVENTORY.md (the inventory that sized the API) and ../PLUGIN-CANDIDATES.md (Links, Docker — done, as a third-party plugin — and Git, next in line) — in French.
In this section
- Create your first pluginPrerequisites: Node 22, and a clone of Mergerie (for the SDK, until it is published on npm: sdk/ of the repository is @mergerie/plugin-sdk).
- The ctx API referenceGenerated from sdk/contract.js (API 1) by sdk/scripts/generer-docs-api.js — do not edit by hand. The examples cited are files under docs/plugins/examples/, run…
- EventsGenerated from sdk/contract.js (API 1) by sdk/scripts/generer-docs-events.js — do not edit by hand.
- A plugin's screenMergerie's front is one global scope, with no build and no modules: index.html lists its <script> and <link> tags in order, and npm run check guarantees that…
- A plugin's dataA plugin reads and writes only tables named plugin_<name>_* (the name with its dashes turned into _: plugin_my_plugin_note). ctx.db.prepare and ctx.db.exec…
- Plugin securityMergerie is a local tool that holds the tokens of your forge, of Jira, of your plugins, and that drives an AI agent on your machine. A plugin is code running…
- Publishing a pluginThe manifest's name is kebab-case (a-z, 0-9, dashes), unique, and it is the folder name: <dataDir>/plugins/<name>/.
- The plugin API and its versionsThe current apiVersion is 1 (sdk/contract.js → API_VERSION). It covers:
- Known pluginsTo be listed: PUBLISHING.md. The list is not a registry — nothing is downloaded automatically, and Mergerie does not check the code of the plugins listed here:…