On this page
Test and publish a plug-in
How to check a plug-in before anyone else adds it, pin its images, and publish it in a catalogue so people can add it and get its updates. To build your first one, read Make your first plug-in.
Test it
The plug-in tester runs the same check Starboard runs before any plug-in is added, and more. Each issue says where it is, what is wrong and how to fix it.
- Errors stop the plug-in being added.
- Warnings should be fixed, such as a card with no
exampleor a plug-in with nohealthpath. - Tips are worth reading, such as a container that can reach your home network.
Accessibility is always tested: every style in light and dark, the labels and hints people read, and every card.
In Starboard
- Go to Settings, then Plug-ins, then Catalogue.
- Under Test a plug-in, choose the plug-in's
starboard-plugin.json. - While its images are not pinned yet, select Allow images without a digest (while you develop it).
- Select Test it.
In the terminal
In a folder with Starboard's files:
python3 -m starboard.plugin_tester path/to/your-plugin
python3 -m starboard.plugin_tester --dev path/to/your-plugin
Give it the plug-in's folder or its starboard-plugin.json. --dev allows images without a digest, as the box does.
From API 1.14 it also checks the logo file next to the manifest, as Starboard
will when it is added, and each card's example for a status Starboard knows. In Test a plug-in, the logo is
checked when you give the manifest's address; a pasted manifest has no address to read it from.
It also checks the update object, warns when changes has nothing for the manifest's own version, and gives a tip
when a plug-in with jobs has no before step (API 1.14).
It ends with how many errors, warnings and tips it found, and exits with 1 when there are errors, so you can run it
in your own checks before each release.
Test an update
Test each new version as people will get it: as an update from the one before, not only as a new install.
- In a test Starboard, add the version before and choose some settings.
- On the plug-in's page, use Update from an address with the new version's address. Check each step in the dialog, the settings after the update, and What is new.
- Select Roll back, and check the settings are as they were.
- Make the health path fail on purpose, update again, and check that Starboard goes back by itself.
Read Write a plug-in that updates safely. Starboard's tools/check-api.sh runs the same
test on an example plug-in, tools/update_smoke.py, on every change to Starboard.
Development mode
Development mode is the tester's Allow images without a digest box, and --dev in the terminal. It lets you
test a manifest whose image has a tag, such as 127.0.0.1:5000/hello-card:0.1.0, and it warns that the image is
not pinned. Adding a plug-in to Starboard always needs every image pinned by digest, even your own. A small registry
on your own server gives you a digest in a few seconds: read
Build it and pin it by digest.
Pin every image by digest
A tag, such as :1.0 or :latest, can point at different code tomorrow. A digest is the image's own fingerprint,
so what people approved is what runs.
- Build and push the image to a public container registry:
docker build -t registry.example.invalid/sam/hello-card:0.2.0 .
docker push registry.example.invalid/sam/hello-card:0.2.0
- Get its digest:
docker inspect --format '{{index .RepoDigests 0}}' registry.example.invalid/sam/hello-card:0.2.0
- Put what it prints in
image, such asregistry.example.invalid/sam/hello-card@sha256:7d2f4b6e8a0c1e3f5b7d9a2c4e6f8b0d1a3c5e7f9b2d4a6c8e0f1b3d5a7c9e2f. - Test again without development mode. It worked when there are 0 errors.
Build each release from a tagged commit, and pin a new digest each time.
Publish the manifest
Put the plug-in's folder somewhere people can reach, such as a public Git repository. Its manifest needs an https
address that gives the file itself, not a web page about it, such as a repository's raw
starboard-plugin.json. People can add a plug-in by that address alone. Read
Add a plug-in by its address.
Give each version its own address, such as a folder per version or a Git tag, so a catalogue can point at each.
Write a catalogue
A catalogue lists your plug-ins and every version of each, so Starboard can offer the right version for each Starboard, and offer updates. The full shape is in Catalogues in the Plug-in API reference.
- Get the SHA-256 of each version's manifest, exactly as it is served:
curl -sL https://example.invalid/hello-card/0.2.0/starboard-plugin.json | sha256sum
Or, for the file on your computer, if it is byte for byte the same:
sha256sum starboard-plugin.json
The first 64 characters it prints are the SHA-256. A change of even one space, or a different line ending, changes it, so check the served file.
- Write
catalogue.json, with the newest version first:
{
"name": "Sam's plug-ins",
"plugins": [
{
"id": "hello-card",
"name": "Hello card",
"description": "Shows on your dashboard how long it has been running.",
"kind": "System",
"author": "Sam",
"permissions": [],
"versions": [
{"version": "0.2.0", "starboard_api": ">=1.4 <2.0", "released": "2026-11-12",
"manifest": "https://example.invalid/hello-card/0.2.0/starboard-plugin.json",
"manifest_sha256": "9b1d3f5a7c2e4b6d8f0a1c3e5b7d9f2a4c6e8b0d1f3a5c7e9b2d4f6a8c0e1b3d",
"changelog": "A list card of the last five starts."}
]
}
]
}
- Publish it at an
httpsaddress that gives the file itself, such as a repository's rawcatalogue.json. - Optional, from API 1.14: add
logo, the plug-in's logo as a data address (data:image/svg+xml;base64,..., up to 24 KB), andlogo_alt, what it shows, so the Catalogue shows the logo before anyone adds the plug-in. Read Catalogues. - To release a new version, add it to
versionswith its own address and SHA-256. Leave the older ones, so people on an older Starboard still get the newest version that works for them.
Never change a manifest after it is listed: Starboard refuses a file whose SHA-256 does not match, and says it changed since the catalogue listed it. Publish a new version instead.
Add a catalogue from a link
To try your catalogue, or to add one someone else publishes:
- Go to Settings, then Plug-ins, then Catalogue.
- Under Catalogue sources, paste the address into Catalogue address.
- Select Add catalogue. Starboard reads it and says how many plug-ins it lists.
Its plug-ins show in their own section, named after the catalogue. Adding a catalogue installs nothing. Starboard reads it again at most once a day. The steps for everyone are in Add a catalogue from a link.
Before you share it
- The tester shows 0 errors without development mode, and you have read every warning.
- Every image is pinned by digest.
- It has a small
logothat passes the tester, and its cards sendstatusandupdatedif it works in the background (API 1.14). permissionslists only what the plug-in uses. People read each one before they add it.homepageandsupport_urlwork, and the readme says what the plug-in does and what it sends anywhere.versionfollows semantic versioning: raise the first number when something stops working the old way.changeslists this version, and says when settings move;update.migrationsmoves any setting you renamed or removed; and an update from the version before works (API 1.14).starboard_apinames the lowest API version with everything you use. Read What each API version added.
Find out more
This page on GitHub, where the help is written.