Skip to main content

Release Process

Versioning​

Semantic versioning; changes recorded in CHANGELOG.md (Keep a Changelog format).

Release checklist​

Nothing here is enforced by a machine on push. GitHub Actions does not execute for this project (Build and deployment), so this checklist is a human procedure plus two automated gates: scripts/verify.sh on a developer's machine, and the per-image checks Coolify runs at build time.

  1. scripts/verify.sh clean — this is the bulk of the list, and it covers gofmt, go vet, go build ./... ./cmd/..., go test -race ./..., AsyncAPI contract drift, the cryptographic inventory, OpenAPI generated-client drift, lint + typecheck + test for the eight portals and apps/mobile, the dependency exception/VEX policy, and SBOM generation.
  2. scripts/verify.sh --with-db with DATABASE_URL set, so the integration suite actually runs against real PostgreSQL + PostGIS. Without the flag it is skipped, and the script says so.
  3. Migrations apply forward on a fresh database, and every new migration has a companion .down.sql — migrate down fails before rolling anything back if one is missing.
  4. Docs site builds (cd apps/docs && pnpm build). This is also the broken-internal-link check: onBrokenLinks: "throw" in docusaurus.config.ts fails the build on one, and the same build runs in apps/docs/Dockerfile, so a broken link stops that image.
  5. OpenAPI documents current for anything the release changes.
  6. Queue the deployment by hand in Coolify — pushing to main deploys nothing. Confirm the one-shot migrate service completed; the long-running services depend on it.
  7. Post-deploy: verify /readyz, watch error rate and p95, confirm the outbox drains.

No vulnerability scan gates a release. govulncheck, trivy, semgrep, gitleaks and go-licenses are configured as workflow steps and have never run against a change. Treat their absence as a known gap rather than as a passed check.

Rollback​

api migrate down [n] exists and has never been run against production. Coolify's redeploy-a- previous-deployment is a vendor claim that has not been exercised on this instance. Prefer forward fixes, and treat rollback as untested until somebody tests it — see docs/architecture/DEPLOYMENT.md §7.