Bludit plugins directory

The database of plugins that Bludit v4 installs from.

Bludit downloads one file, index.json, and shows the plugins in Admin panel → Plugins → Add a plugin. From there an administrator installs, updates and deletes plugins without touching FTP.

This repository holds metadata only. The code of each plugin stays in the repository of its author, and index.json points at a zip attached to a GitHub release, together with the sha256 of the exact bytes that were reviewed.

For people using Bludit

Nothing to do here. Open the admin panel and use Add a plugin.

A plugin that is not listed, for example a commercial one, can still be installed from the same page with Upload a plugin.

For plugin authors

Adding a plugin is one JSON file and a pull request. See CONTRIBUTING.md.

Every pull request is analyzed automatically: the zip is downloaded, unpacked and inspected, the PHP is checked, and a comment tells you exactly what needs fixing. You can run the same checks yourself before opening the pull request:

python3 .github/scripts/analyze.py plugins/your-plugin.json

# or, before you publish the release, against a local zip
python3 .github/scripts/analyze.py plugins/your-plugin.json --zip build/your-plugin.zip

Layout

Two directories matter if you are adding a plugin:

Path	What it is
plugins/<id>.json	One submission per plugin. The only thing you write.
templates/plugin.json	Starting point for a submission.
templates/release.yml	Drop-in workflow that builds the zip in your own repository.

Everything else is the machinery, kept out of the way under .github:

Path	What it is
index.json	Generated by CI, at the root because Bludit downloads it from there. Never edit it by hand.
.github/scripts/	The analyzer, the index builder and the health check.
.github/rules/	What a submission is validated against: the schema, and the ids and class names already used by Bludit core.
.github/tests/	Fixtures that pin what every rule reports, run by the self test.

Workflows

Workflow	When	What it does
analyze.yml	Pull request	Downloads and inspects the plugin. Read-only token, no secrets, never comments.
report.yml	After analyze.yml	Posts the comment and sets the labels. Never runs code from the pull request.
build.yml	Merge to main	Rebuilds and commits index.json.
healthcheck.yml	Weekly	Re-checks every asset still exists and still matches its checksum.

The split between analyze.yml and report.yml is deliberate. Analyzing a submission means running code supplied by whoever opened the pull request, so that job gets a read-only token and no secrets. Only the second workflow, which never touches that code, is allowed to write.

Bundled plugins

Plugins that ship with Bludit live in bl-plugins/ so a fresh install works without a network connection. They are not listed here, and an id or a class name already used by one of them is rejected, see .github/rules/.