Skip to main content

Release the Backend to Prod

Symptoms​

A commit on main has run on staging and the team agreed to ship it.

Impact​

  • The prod api restarts (rolling). DB migrations in the release run at its boot and are one-way.
  • If the broker changed since the last release, the prod broker restarts first: every WebSocket drops and clients reconnect. Announce it.

Steps​

  1. Pick the commit: the newest commit on main whose staging deploy ("ci: push image and deploy to Northflank (staging)") is green. A docs-only merge deployed nothing and can't be promoted.

  2. Pick the version:

    • a major for any breaking API change (the promote checks it against the published contract);
    • otherwise a minor for new features, a patch for fixes.
    • It must be above every published version.
  3. Check the migrations the release adds, and plan their effect on prod data:

    git diff --stat v<last version> <commit> -- internal/database/migrations
  4. Dry run. Actions → "Prod - Promote Staging Image to Prod" → Run workflow:

    FieldValue
    Use workflow frommain
    staging_shathe commit (7 to 40 characters)
    versionthe version
    dry_runchecked
    release_summaryempty

    It runs every guard and changes nothing. Check the preflight job's logs (the staging proof names the qubital-infra commit and says verified; the scans are also in the run summary) and the contract-guard job's last step (No breaking changes …, or a breaking change that needs a major).

  5. Release. Run the workflow again with the same inputs, dry_run unchecked, and a release_summary of one to three sentences.

  6. If it fails, read the failed step, fix the cause, then Re-run all jobs. Never "Re-run failed jobs": the deploy jobs refuse it, because it would reuse an earlier attempt's guards.

Verification​

  • The run is green; the GitHub Release v<version> exists and its notes name the qubital-infra commits.
  • curl -fsS https://api.qubital.space/health answers.
  • Sign in to the desktop app against prod, send a chat message, change your presence.

Escalation​

The team owner (Northflank and repository owner).