Aller au contenu

Set up a plugin repository

Ce contenu n’est pas encore disponible dans votre langue.

The plugin development guide covers writing the plugin itself: inheriting the base classes, declaring metadata fields, installing it locally. This page covers the repository around it. Everything here is per project: each plugin lives in its own GitLab repository, pins its own dependencies and carries its own CI, so nothing is inherited from madbot.

Plugins live under ifb-elixirfr/madbot/plugins, in official/ or community/. The steps are the same for both.

In pyproject.toml, the dev extra holds the tools that the CI runs, and the two that publish a release:

[project.optional-dependencies]
dev = [
"ruff",
"bandit[toml]",
"safety >= 3.8.0",
"build >= 1.4.2, < 2",
"twine >= 6.2.0, < 7",
]

pip and setuptools carry advisories of their own: give them a floor in [tool.pixi.dependencies], and in the build system.

[tool.pixi.dependencies]
pip = ">=26.2.2,<27"
setuptools = ">=83.0.0"
[build-system]
requires = ["setuptools >= 83.0.0"]
build-backend = "setuptools.build_meta"

The CI calls tasks, never raw commands, so the same checks run the same way on a laptop and in a pipeline:

[tool.pixi.tasks]
lint = { cmd = "ruff check .", default-environment = "dev" }
format = { cmd = "ruff format .", default-environment = "dev" }
format-check = { cmd = "ruff format --diff .", default-environment = "dev" }
safety = { cmd = "safety check", default-environment = "dev" }
bandit = { cmd = "bandit -c pyproject.toml -r <your_package>", default-environment = "dev" }
quality-check = { depends-on = [
{ task = "lint" },
{ task = "format-check" },
{ task = "bandit" },
{ task = "safety" }
] }

Run pixi run quality-check before opening your first merge request. A new repository usually fails safety straight away: see step 5.

3. Get plugins-api from the madbot registry

Section titled “3. Get plugins-api from the madbot registry”

plugins-api is published to the package registry of the madbot project on GitLab, not to PyPI. Depend on the major your plugin is written for, and add the registry as an extra index, for pixi:

[project]
dependencies = [
"plugins-api >=3.0.0,<4",
]
[tool.pixi.pypi-options]
extra-index-urls = [
"https://gitlab.com/api/v4/projects/ifb-elixirfr%2Fmadbot%2Fmadbot/packages/pypi/simple",
]

and for pip, in .gitlab-ci.yml:

variables:
PIP_EXTRA_INDEX_URL: "https://gitlab.com/api/v4/projects/50871918/packages/pypi/simple"

To run your plugin against a change of plugin_api/ that is not released yet, see Develop against a local plugins_api.

A plugin runs inside the Django process of madbot-api. Whatever Django your plugin resolves in its own environment is not the one it runs with: in production it gets the API’s. plugins-api carries the right range, so a plugin that depends on it needs nothing more. If your plugin declares Django itself, pin it to the range that madbot-api uses, currently >=5.2.18,<5.3.

A loose django>=4.1 floats to the newest release, drifts out of the API’s range, and collects advisories that do not even apply to how the plugin is deployed. That happened, and cost eleven advisories on one plugin.

Copy .gitlab-ci.yml from an official plugin. The parts that matter:

.base:
retry:
max: 2
when:
- api_failure
- stuck_or_timeout_failure
- runner_system_failure
tags: [docker, XL, nncr, idris]
image:
name: ghcr.io/prefix-dev/pixi:latest
pull_policy: always
before_script:
- pixi global install git
- pixi install -e dev
stages:
- 💎 quality
- 🛡️ security
Code audit (ruff):
extends: .base
stage: 💎 quality
script:
- pixi run lint
- pixi run format-check
only:
- merge_requests
Dependencies vulnerability (safety):
extends: .base
stage: 🛡️ security
script:
- pixi run safety
only:
- merge_requests
Security breach (bandit):
extends: .base
stage: 🛡️ security
script:
- pixi run bandit
only:
- merge_requests

If your plugin publishes releases, add the release stage of an existing plugin as well.

5. Fix what safety reports, and record why

Section titled “5. Fix what safety reports, and record why”

A new repository almost always fails pixi run safety on its first run, because its lock has been resolving freely since the day it was created. Fix each finding by pinning above the affected range, with a comment that names the advisory, so the next reader knows why the pin exists:

# NOTE: Safety reports vulnerability in nltk < 3.10.1 (CVE-2026-72818)
"nltk>=3.10.1",

Then run pixi lock and pixi run safety again. Worth knowing:

  • Prefer a lock refresh to a manifest change when the existing range already allows a fixed version. pixi update <package> often clears an advisory without relaxing or tightening anything you declared.

  • Pin transitive dependencies where they actually come from. urllib3 and idna arrive through requests, which is a runtime dependency, so they belong in dependencies and not in the dev extra.

  • When an advisory has no fixed version yet, and the affected code is never called, ignore that one advisory in the safety task, with a comment that says why and when to drop it:

    # NOTE: SFTY-20260902-58666 flags every nltk release, with no fixed version
    # yet. nltk is only pulled by safety itself, which never calls the affected
    # APIs. Drop the ignore once nltk ships a fix.
    safety = { cmd = "safety check --ignore SFTY-20260902-58666", default-environment = "dev" }

If safety reports something on your machine that is not in pixi.lock, it is scanning a Python outside the pixi environment: check with grep -c '<package>' pixi.lock before chasing it.

A safety advisory is published against code that is already released, so nothing in merge_requests fires when one lands: without a scheduled run, an advisory stays invisible until someone happens to open a merge request. That is how CVE-2026-13346 went unnoticed for weeks.

Add schedules to the safety job, and a report of the dependencies that are behind, which only runs on schedules:

Dependencies vulnerability (safety):
extends: .base
stage: 🛡️ security
script:
- pixi run safety
only:
- merge_requests
# Weekly schedule. A safety advisory is published against code already
# released, so nothing in `merge_requests` fires when one lands.
- schedules
Dependency updates:
extends: .base
stage: 🛡️ security
script:
# `update`: newer versions the current constraints already allow.
- pixi update --dry-run --no-install
# `upgrade`: newer versions a pin in pyproject.toml is blocking.
- pixi upgrade --dry-run --no-install
allow_failure: true
only:
- schedules

Dependency updates is a report, not a breakage: on a merge request it would be noise. Both pixi commands exit 0 whether or not anything is behind, so the report is the job log, and --dry-run writes neither the lock nor the manifest.

A pipeline schedule is a project setting, not CI configuration, so it cannot live in .gitlab-ci.yml. In the plugin project, open Build → Pipeline schedules → New schedule:

  • description: Contrôle de sécurité hebdomadaire;
  • a cron on Monday morning, ten minutes after the previous plugin’s, with the timezone Europe/Paris;
  • target branch: the default branch, dev (or main);
  • leave Activated unchecked until the merge request that adds the schedules trigger has landed.

Then check it, because the failure is silent: a schedule whose pipeline matches no job creates no pipeline at all, and GitLab reports nothing, neither in the schedule list nor in the pipeline list. After activating it, run the schedule once from the same page and check that the pipeline holds Dependencies vulnerability (safety). Do not wait until Monday to find out.

A schedule is owned by whoever creates it, and runs with that person’s permissions. If they are later blocked or removed from the project, the schedule silently becomes inactive. Create schedules with the shared bot account rather than your own; if one becomes inactive, any Maintainer can reactivate it with Take ownership.

Creating a schedule that targets a protected branch also requires permission to merge into that branch: the account needs the Maintainer role, not Developer.

  • ruff, bandit and safety in the dev extra
  • pip and setuptools floors in [tool.pixi.dependencies] and [build-system]
  • lint, format-check, safety, bandit and quality-check pixi tasks
  • plugins-api from the madbot registry, in pixi and in the CI
  • Django comes from plugins-api, or is pinned to the API’s range
  • .gitlab-ci.yml with the quality and security stages
  • pixi run quality-check passes locally
  • the safety job runs on schedules as well as merge_requests
  • a schedule-only, allow_failure Dependency updates job
  • a pipeline schedule, owned by the bot account
  • the schedule run once by hand, with the safety job in its pipeline