Shipping an upgrade
- Bump metadata.version above every reviewed version.
- Make sure spec.compatibility.control_api covers the target control planes; ones that do not match cannot install or upgrade to it and keep their last compatible version.
- Any permission change sends the version to human review, and customers confirm new permissions when upgrading.
- Release notes say what changed, the minimum control plane version, whether permissions were added, how configuration migrates and how to recover from a failure.
A failed upgrade leaves the installation in upgrade_failed_lkg_preserved with the last good version kept. That does not replace your own data migration and rollback; how to roll back depends on the kind and supported versions, so document recovery steps and never ask customers to edit a database.
After disable and uninstall
After disabling or revoking permissions, new events and replays are authorisation-checked too. Your service must recognise the revocation, stop using revoked API keys and installation identities, not retry refused requests forever, and handle data you hold as agreed with the customer.
Disabling or uninstalling changes the installation only: its pages go and business subscriptions bound to it get no new events or replays. The API key the customer created for your service and test-only subscriptions are not tied to the installation and are not revoked automatically; the customer handles each one. Put this checklist in your plugin notes for the customer:
- You pause your service’s scheduled jobs and writes to the customer’s control plane first.
- The customer revokes the key made for this plugin on the “API key” page (/dashboard/account/api-key). Check nothing else shares it first; if something does, give that work its own key before revoking, never delete a shared key outright.
- The customer revokes business and test-only subscriptions no longer needed on the “Plugin webhook subscriptions” page (/dashboard/sys/plugin-webhooks); test-only subscriptions are not bound to the installation, so disabling or uninstalling leaves them active.
- The customer’s installation manager disables or uninstalls the plugin with a reason and refreshes to check the state.
- You delete keys, webhook secrets and installation signing keys you no longer need, and handle data you hold as agreed.
- Check together: the plugin pages are gone, the old key gets 401, business events have stopped, test-only subscriptions are revoked, and other plugins and shared keys are unaffected.
In an emergency, revoke the dedicated key before disabling the installation. Your service must recognise the revocation and not retry refused requests forever. A complete delivery verifies at least: a first install, an upgrade, use by an ordinary user and by an administrator, a dependency outage, revoked permissions, repeated requests, the last good version after a failed upgrade, and pages, calls and events all stopped after following the checklist above.
Troubleshooting
| Symptom | Check first | Next step |
|---|
| Cannot open “My plugins” | Onboarding status, current entity, team role | The owner checks the application and member roles |
|---|
| Key verification fails | Expired challenge, partial copy, wrong key | Get a new challenge and sign again |
|---|
| Namespace conflict | Claimed by another publisher, reserved prefix | Use your own namespace |
|---|
| Signature or digest mismatch | Same pack run? Edited after signing? | Pack and sign again from the sources |
|---|
| Tool exits 0 without output | Did it print the check and output lines? | Run again from the real path given by pwd -P and check the files |
|---|
| Version already exists | Version list and detail | Continue with it if created; bump the version to change files |
|---|
| Approved but customers cannot see it | Published? Channel, compatibility, price plan | Check each one; do not keep changing files |
|---|
| Fetched but nothing works | Confirmed, enabled, configured? Current role | Verify with the target role where it mounts |
|---|
| Free plugin cannot be fetched | An active zero-price plan? | The owner adds one under “Pricing” |
|---|
| Calls refused | Installation state, approved permissions, credential type and scope | Follow the operation’s auth; never switch to a more privileged account |
|---|
When contacting support give the plugin ID, version, time, request_id, error code and redacted screenshots. Never send passwords, private keys, API or webhook secrets, or raw customer data.