# Publishing a plugin

Publishing needs nothing but a public git repository:

```bash
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:

```bash
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.