Releases and updates

Stable GitHub Releases are the production deployment interface. Publishing a non-draft, non-prerelease tag named vX.Y.Z runs the unified release workflow against that exact commit. One release deploys the API, portal, browser app, and this documentation site; starts both EAS store submissions; and attaches the OBS plugin packages to the same GitHub Release.

Before tagging

Set the same X.Y.Z (no leading v) in:

• apps/native/app.json
• apps/native/package.json
• every MARKETING_VERSION entry in the committed iOS project
• apps/obs-plugin/buildspec.json

Tag a commit on main and publish the release. Draft and prerelease publications are ignored, and concurrent releases are serialized.

What the workflow does

1. Runs the repository tests, type checks, and every production build first — a red check stops the release before anything deploys.
2. Connects to the app host over an ephemeral Tailscale identity and runs the root-owned visp-release bootstrap with the tag and its 40-character commit SHA.
3. Starts EAS builds that submit Android to Play internal testing and iOS to the VISP Internal TestFlight group.
4. Builds, signs, and notarizes the OBS packages and attaches them with SHA256SUMS.txt — uploads use overwrite semantics, so rerunning a failed job is safe.

How the server update stays safe

The bootstrap verifies the tag and SHA, takes a host lock, refuses to run over tracked local changes, checks out the exact release, and then executes that release's own helper from /usr/local/libexec — so helper fixes take effect in the same release that ships them.

The helper installs frozen dependencies, migrates the database, and builds all four app-host artifacts before restarting anything. It validates the Caddy configuration before installing it, restarts visp-server and visp-web, reloads Caddy, and runs local smoke checks. An install, migration, or build failure therefore leaves the currently running services untouched.

Two rules follow from this design:

• Migrations must stay backward-compatible; database rollback is manual.
• A MediaMTX (relay) restart is never part of a release. Schedule relay upgrades in a maintenance window because they end active streams. API and portal restarts do not.

After the release

• Portal and API healthy; a deep browser-app route and OAuth return work at stream.visp-stream.com; WebRTC publishes through the relay.
• Docs respond at docs.visp-stream.com: /docs, /api/search, /llms.txt, /llms-full.txt.
• Expo shows Android in Play internal testing and iOS in TestFlight.
• The GitHub Release carries all three OBS packages, the macOS package is notarized, and every file matches SHA256SUMS.txt.

Store promotion to public production, OBS plugin installation on broadcaster machines, OTA updates, automatic database rollback, and relay restarts are intentionally outside the workflow. Operator-side prerequisites (environment files, GitHub environment variables and secrets, DNS) are documented in the repository's deploy/UPDATE.md.