Publishing and releases

Repository and addon ID

Host your addon in a public GitHub repository. The manifest id must match the repository path on GitHub:

Format: ORG/REPO — GitHub organization or user name, slash, repository name.

The id is stable across releases. It is used in:

• HTTP routes (/addon/{id}/…, /addon_static/{id}/…)
• depends_on references between addons
• Update checks (catalog API and GitHub releases)

Do not change the id after the first public release unless you treat it as a new addon.

GitHub release layout

Publish each version as a GitHub Release. Attach these files to the release:

Recommended contents of main.zip:

main.zip
├── manifest.json
├── index.js              # when the addon has a worker
├── logo.png              # or logo.svg
├── index.html            # when web UI is used
└── ...                   # other assets (web_contents, media, etc.)

The StreamKit+ catalog backend and the app's update checker read the manifest.json release asset to determine the published version. Keep version in that file in sync with the release tag (for example tag v1.2.0 → "version": "1.2.0"). The release asset must be byte-identical to manifest.json inside main.zip (required for catalog sync).

Checklist before publishing

1. manifest.json id equals ORG/REPO for your GitHub repository.
2. version matches the GitHub release tag.
3. Release contains main.zip, manifest.json, and logo.png / logo.svg.
4. main.zip includes every file required to run the addon (including manifest.json and the icon).
5. Permissions in the manifest match what the addon actually uses.
6. After publishing the release, trigger a catalog sync (on the site or via the sync API) so users receive the new files.

Catalog file caching

When your addon is added to the catalog, the site downloads the release assets (manifest.json, logo.png / logo.svg, main.zip) and caches them permanently.

• Cached files are served to all users and are not re-fetched automatically.
• They are refreshed only when a version sync runs — manually on the site (Update version) or through the sync API.

Once your addon has been moderated and approved, the files users download stay exactly as reviewed. Changing files in a GitHub release without running a sync does not change what users get. This is intentional and protects users from silent post-moderation file swaps.

To ship a new version, publish a new GitHub release and trigger a sync.

Catalog sync validation

When adding or syncing an addon, the catalog checks that:

1. The release contains manifest.json, logo.png (or logo.svg), and main.zip.
2. The id in manifest.json matches your repository using the same rules as manifest.json: ORG/REPO for third-party repositories, or REPO (repository name only) for addons in the RocketMan-StreamKit organization.
3. The manifest.json release asset is identical to the manifest.json inside main.zip.

If any check fails, the add or sync is rejected with an explanatory error.

Automatic catalog version sync

Use the developer sync API to refresh the catalog after each GitHub release, without opening the site and clicking Update version manually.

Base URL in examples: https://rocketman-streams.com. Use the domain of the site where your addon is published.

Developer token

1. Open the Addons page on the site.
2. Click the API key button at the top.
3. Copy your developer token from the modal.

You can regenerate the token from the same modal (with confirmation). Regenerating immediately invalidates the old token — update it everywhere it is used.

Keep the token secret. Anyone with it can trigger version updates for your addons. Store it as a CI/CD secret (for example a GitHub Actions secret named ROCKETMAN_ADDON_TOKEN) and never commit it to your repository.

Sync API

POST https://rocketman-streams.com/api/extensions/dev/sync
Content-Type: application/json

Parameters may also be sent as application/x-www-form-urlencoded or URL query parameters; JSON is recommended.

On success the endpoint re-reads the latest GitHub release, re-downloads and refreshes the cached files, and updates the stored version and metadata when the release changed.

Example:

curl -X POST "https://rocketman-streams.com/api/extensions/dev/sync" \
  -H "Content-Type: application/json" \
  -d '{"repo":"OWNER/REPO","token":"YOUR_TOKEN"}'

Success response:

{
  "status": true,
  "repo": "OWNER/REPO",
  "updated": true,
  "version": "1.2.3"
}

• updated — true if version or metadata changed compared to what was stored; false if the release was re-read but nothing changed.
• version — the version after the sync.

Error responses (HTTP status plus error field):

Rate limits

• 1 request per 30 seconds per developer token.
• 1 request per 60 seconds per repository.

When rate-limited, the response includes retryAfter (in seconds).

GitHub Actions example

This workflow runs on every published release and notifies the catalog. Save it as .github/workflows/rocketman-sync.yml in your addon repository and add a repository secret named ROCKETMAN_ADDON_TOKEN with your developer token.

name: Sync addon to RocketMan catalog

on:
  release:
    types: [published]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Notify catalog about the new release
        run: |
          curl -sS -X POST "https://rocketman-streams.com/api/extensions/dev/sync" \
            -H "Content-Type: application/json" \
            -d "{\"repo\":\"${{ github.repository }}\",\"token\":\"${{ secrets.ROCKETMAN_ADDON_TOKEN }}\"}"

Related reading

• manifest.json — field reference
• Getting started — project layout during development