Mergerie
Contents

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.

  1. Open Settings → Plugins. The list shows every plugin: version, state, permissions, dependencies, events listened to and emitted.
  2. 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).
  3. Still in Settings → Plugins, Hello's form (generated from its settingsSchema) has a Greeting field. Change it, Save: GET /api/plugins/hello/ping answers with the new value, and the tab shows it.
  4. Start a session, a review, a verification: the Hello tab lists the events received (session.finished, review.completed…), with their payload and its version.
  5. 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.

PageFor
GETTING-STARTED.mdcreate your first plugin with the generator, test it without Mergerie, install it
API.mdthe ctx reference, primitive by primitive, with permission, signature, errors
EVENTS.mdevery event, when it is emitted, its payload and version
UI.mdwhat a plugin adds to the screen and the window.mergerie kit
DATA.mdtables, prefix, migrations, P/L/C classification, retention
SECURITY.mdthe trust model, what a plugin cannot do
PUBLISHING.mdnaming, documenting, publishing (AGPL licence), getting listed
MIGRATION.mdhow apiVersion evolves, and what the core guarantees
COMMUNITY.mdknown 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

  1. 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).
  2. 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…
  3. EventsGenerated from sdk/contract.js (API 1) by sdk/scripts/generer-docs-events.js — do not edit by hand.
  4. 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…
  5. 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…
  6. 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…
  7. Publishing a pluginThe manifest's name is kebab-case (a-z, 0-9, dashes), unique, and it is the folder name: <dataDir>/plugins/<name>/.
  8. The plugin API and its versionsThe current apiVersion is 1 (sdk/contract.js → API_VERSION). It covers:
  9. 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:…