qsys-plugin-registry-beta/docs/SETUP-runbook.md

Beta channel — one-time setup runbook

Goal: stand up a beta feed that Q-SYS testers can add without touching the production feed. You do this once; after that, publishing a beta is just the five steps in the README.

Placeholders used below (matching your production setup):

• Gitea host: 3f4dzl.gitea.cloud
• Org: visionary-plugins
• Beta package id: Visionary-PacketAV-Suite-Beta

---

1. Create the beta repo in Gitea

Same org as production (packages are owned by the org, so the beta package will sit alongside prod in the org's Packages list — that's expected).

1. In Gitea: visionary-plugins org → New Repository.

2. Name it qsys-plugin-registry-beta. Set visibility however you like — repo visibility does not affect the feed. The package feed's anonymous readability comes from the org being Public, which it already is for prod. (If the org is Public, the beta package is anonymously readable too.)

3. Push this scaffold to it:

   cd qsys-plugin-registry-beta
   git init -b main
   git add .
   git commit -m "Beta channel scaffold"
   git remote add origin https://3f4dzl.gitea.cloud/visionary-plugins/qsys-plugin-registry-beta.git
   git push -u origin main
   

2. Add the publish token

Same token as production works — a Gitea PAT with package read/write scope is org-wide, so it can publish Visionary-PacketAV-Suite-Beta too.

• Beta repo → Settings → Actions → Secrets → add PACKAGE_TOKEN with the same value you used for the prod repo.
• Confirm a runner is available to the repo (Settings → Actions).

3. Publish a first beta build

1. Put a beta .qplugx set (or just copy the current prod content for a smoke test) + icon.png into plugins/VisionarySolutions_Suite_Beta/content/.

2. Commit and push.

3. Actions → Publish Q-SYS plugins → Run workflow.

4. Verify the feed the same way as prod, anonymously:

   curl https://3f4dzl.gitea.cloud/api/packages/visionary-plugins/nuget/registration/Visionary-PacketAV-Suite-Beta/index.json
   

   You should see JSON listing the beta version(s).

4. Cloudflare short-links (301 redirects)

Add two aliases next to your existing packetav / versions rules. Point them at the beta package's registration URL and the beta versions file.

Short link	301 target
vsplug.in/packetav-beta	https://3f4dzl.gitea.cloud/api/packages/visionary-plugins/nuget/registration/Visionary-PacketAV-Suite-Beta/index.json
vsplug.in/versions-beta	raw URL of versions-beta.json in your assets repo, e.g. https://3f4dzl.gitea.cloud/visionary-plugins/assets/raw/branch/main/versions-beta.json

Then, in a browser (logged out), open https://vsplug.in/packetav-beta and confirm it lands on the registration JSON — QSC's backend must be able to follow the redirect, exactly as it does for the prod link.

5. Seed the beta update feed

Put versions-beta.json (in this repo's docs/) into the assets repo root so vsplug.in/versions-beta resolves. Keep its package value equal to the beta nuspec <version> and the plugins map equal to the beta build's plugin versions. Update it every time you publish a new beta.

6. Beta icon (optional but recommended)

The nuspec references icon-beta.png in the assets repo so beta is visually distinct in Asset Installer. Drop a beta-badged icon there, or change the iconUrl back to the prod icon.png if you'd rather not bother.

---

Version lineage rules (same discipline as prod)

• Beta <version> is 3-part SemVer only — a 4-part number makes the whole package vanish from Asset Installer.
• Strictly ascending. The beta counter is independent of the prod counter; don't try to keep them in sync.
• No prerelease -beta suffix on the number itself — Q-SYS filters those. The channel separation is the package id, not a version tag.

Promotion flow (beta → production)

1. Copy the same .qplugx files from the beta content/ into the prod repo's content/.
2. Bump the production nuspec <version>.
3. Commit/push and run the prod publish workflow.
4. Update the prod versions.json.

Because the plugin files (and their PluginInfo.Ids) are byte-identical, this is a re-wrap, not a rebuild — what testers validated is exactly what ships.

Retiring a beta build

Delete old beta versions from the org's Packages page anytime — beta has no field-install guarantees, so same-version delete/republish is fine here.