OPSAVOR docs
Menu

Home › Running the fleet

Developing and promoting plugins

For engineers: where plugins live, what the checks do on each push, beta and stable tags, promoting a plugin a customer built, and the plugin kit.

Where plugins live

Every store plugin has its own repository in the platform-plugins organization on Gitea, named after the plugin's id. Start a new one from the plugin-template repository: Use this template, rename it, and replace plugin.json. Usually that one file is the plugin. An app also ships one JavaScript file for work the manifest cannot describe; its README says what it does and what it asks for.

The full developer guide (every field, the data a plugin can read, and the checks) is in the platform repository under docs/plugins/: docs/plugins/README.md. This page is only the staff workflow around it.

The plugin kit

Check a plugin before you push, from a checkout of opsavor/platform beside the plugin's repository:

node ../platform/bin/plugin.mjs validate plugin.json --tier store
node ../platform/bin/plugin.mjs run plugin.json --sample
node ../platform/bin/plugin.mjs run plugin.json --plane /path/to/a/copy/of/plane.db --json

What happens on every push

The same workflow (.gitea/workflows/plugin.yml) runs in every plugin repository, on pushes to main, on pull requests and on tags that start with v. Work through pull requests.

  1. Get the plugin kit. It clones opsavor/platform with a read-only token.
  2. Validate. The manifest is checked for the store tier.
  3. Run it against the sample business.
  4. Run it on its dev tenants' records. The fleet runs the plugin on each of its dev tenants, and the build prints what it computed. A calculation that fails there fails the build. With no dev tenant it only reminds you to add one.
  5. On a tag only: the tag must equal the manifest's version, and then the version is published to the store.

The workflow needs two organization secrets (platform-plugins, Settings, Actions, Secrets):

If one is missing, the build fails and says which. Set it, then run the build again.

Beta, then stable

  1. Give it a dev tenant in the console (Plugins, then Develop a new plugin or Develop on it), even before anything is published.
  2. Tag vX.Y.Z-beta.N, for example v0.2.0-beta.1. Only tenants on the beta channel get it. A dev tenant installs it within the hour, or at once if it can be reached, and the store approves it there.
  3. Tag vX.Y.Z when it is right. It goes to every customer given the plugin on stable, and their owners approve what it asks for.

Bump version in plugin.json before each tag. A published version never changes. The store signs it and refuses the same version with different content, so a fix is always a new version. A bad version can be retired on the Plugins page (admins only).

After a stable release, give the plugin to customers on their Plugins tab, but only those whose platform release supports what it uses. See Plugins and the store.

Promoting a customer's plugin

An owner can build a plugin in their own copy (it shows there as built here) and press Offer to OPSAVOR. Only the plugin is sent, never their records.

  1. In the console, open Plugins and find it under Offered by customers.
  2. An admin presses Start a repository. A repository is made in platform-plugins with the template's checks and the customer's plugin as its start. Its version starts at 0.1.0 and its manifest replaces the customer's plugin (local:<their plugin id>).
  3. Give it a dev tenant (the customer's own tenant, if they agree), improve it, tag a beta, then tag a stable version.
  4. Where the customer runs their own version, the store plugin takes its place once installed there. They see theirs as Replaced by a store plugin.

If you do not want it, press Set aside. Making repositories needs a Gitea token set on the fleet. If there is none, the console says so, and Copy manifest lets you start the repository by hand.