Publishing a plugin

Publishing needs nothing but a public git repository:

git tag v0.1.0 && git push --tags

Anyone can then install it with noodlelab plugins add git+https://github.com/you/noodlelab-thermo. It is unverified: nothing has checked it, and shared servers do not install unverified plugins by default.

Releases

The scaffold’s .github/workflows/release.yml runs check-plugin, the examples and the tests on every push. On a version tag it also builds a wheel, signs it with a GitHub build attestation (Sigstore: no keys to manage) and attaches it to the GitHub release. An index lists that wheel, so installs download exactly the file your workflow built, check its SHA-256, and verify the attestation (with the gh CLI) before installing it. Nothing of the plugin runs while it is installed.

Never move a release tag. An index freezes a plugin whose tag starts pointing at another commit, and installs refuse it, because that is how a hijacked repository would deliver new code under an old version. Fix a release with a new one.

Plugin indexes

An index lets people install a plugin by name, search for it, and see what it requires before installing. It is a static index.json, rebuilt from a repository of registrations by a GitHub Action and served by GitHub Pages: it costs nothing and needs no server.

To be listed in the public index, either add the GitHub topic noodlelab-plugin to your repository, or open a pull request adding plugins/<name>.toml with one line, repository = "https://github.com/you/noodlelab-<name>". Names are first come, first served; noodlelab’s own names, and names one letter away from a listed one, are refused.

Each version is checked when it is listed (manifest, plugin API, imports, permissions); one that fails is shown as not installable, with the reasons.

A private index

A company can run its own index for internal plugins:

noodlelab plugins init-index plugin-index   # the repository: README, workflow, advisories

Push it, turn on GitHub Pages (source: GitHub Actions), and add its index.json URL to Admin → Plugins → Policy → Private indexes (or plugin_indexes in the settings). The index can also be a file on a shared drive: noodlelab plugins build-index <folder> -o index.json builds it anywhere, and an index may be a path.

PyPI

Plugins do not need PyPI. One that is also published there can say so in its index entry, and installs then use PyPI’s wheels. noodlelab’s own plugins are published there too, so that pip install "noodlelab[engineering]" keeps working.