#12. Updates, Versioning & CI

#12.1 Manifest versioning

• version follows SemVer. Hosts MAY warn (never silently block) on a downgrade or a skipped major version.
• addonium (the spec version) follows its own major.minor; a host should refuse manifests whose major spec version it doesn't implement.

#12.2 Self-describing update pointer

{
  "update": {
    "manifestUrl": "https://example.com/.well-known/addonium/manifest.json",
    "checkInterval": 86400
  }
}

A host periodically re-fetches manifestUrl (default: once every checkInterval seconds, or on next app launch if omitted) and diffs version. No addon needs to "push" anything - this is a plain polling pointer, deliberately boring and infrastructure-free.

#12.3 GitHub Actions: auto-updating manifest.json

A common author setup is: source of truth lives in a small addon.yaml or package.json, and a workflow regenerates and republishes manifest.json (e.g. to GitHub Pages or a gh-pages/dist branch) on every push, keeping version and update.manifestUrl in sync automatically.

# .github/workflows/addonium-publish.yml
name: Addonium: Build & Publish Manifest

on:
  push:
    branches: [main]
  workflow_dispatch: {}

permissions:
  contents: write
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Bump patch version
        id: bump
        run: |
          CURRENT=$(jq -r .version manifest.source.json)
          NEXT=$(node -e "const [M,m,p]=process.argv[1].split('.').map(Number);console.log(\`\${M}.\${m}.\${p+1}\`)" "$CURRENT")
          echo "version=$NEXT" >> "$GITHUB_OUTPUT"

      - name: Render manifest.json
        run: |
          jq --arg v "${{ steps.bump.outputs.version }}" \
             '.version = $v' manifest.source.json > manifest.json

      - name: Validate against Addonium schema
        run: npx ajv-cli validate -s addonium.schema.json -d manifest.json

      - name: Commit updated manifest
        run: |
          git config user.name "addonium-bot"
          git config user.email "bot@users.noreply.github.com"
          git add manifest.json
          git commit -m "chore: publish manifest v${{ steps.bump.outputs.version }}" || echo "nothing to commit"
          git push

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

This gives an author, for free:

• Auto version bumping on every merge to main.
• Schema validation before publish, so a broken manifest never goes live.
• A stable manifestUrl (GitHub Pages / raw.githubusercontent.com) hosts can poll - no server required at all for Open Addons that are purely static.

#12.4 Optional registry / index

Addonium does not require centralized discovery, but authors who want to be listed somewhere can publish an index.json entry to a community registry repo (à la a package registry's PR-based index), containing just { id, name, manifestUrl, type }. A registry is a directory, not an authority - it never gates whether an addon works, only whether it's easy to find. A second workflow can validate/lint such submissions:

# .github/workflows/addonium-registry-check.yml
name: Addonium: Registry Submission Check
on:
  pull_request:
    paths: ["registry/**.json"]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate submitted entries
        run: |
          for f in registry/*.json; do
            npx ajv-cli validate -s registry-entry.schema.json -d "$f"
            curl -fsSL "$(jq -r .manifestUrl "$f")" | npx ajv-cli validate -s addonium.schema.json -d /dev/stdin
          done