1
Release Process
Sam Catlow edited this page 2026-10-11 14:40:58 +11:00

Automated release process

Guide home · Previous: staging and QA · Next: road to 1.0

This is the target process. The migrated repository still has the previous GitHub-oriented publishing workflow; these stages must be implemented before they become operating instructions.

Select candidate → validate source → build artifacts → stage and run QA → approve → deploy → verify production → publish stable.

A successful release means the selected artifacts are running and verified. Publication is one stage of that result.

1. Select and freeze the candidate

Choose a bounded scope, intended version, and exact commit. Finish release notes before building so the notes and artifacts describe the same source. One version covers all five host services and the agent image.

Use 0.1.0 for the first new release. Reserve 1.0.0 until the product criteria are met. Once a version is assigned to a candidate, retain its identity and evidence. If a source fix is needed, create a new candidate with a new version rather than moving an existing tag or replacing its assets.

A tag identifies source; a successful build alone does not mark it stable. Store candidates privately as draft releases or equivalent private artifact records. Do not update stable image aliases at candidate build time.

2. Validate source and build once

Run the authoritative task check, the full Go test suite through task test:full, and the required release-specific checks. Preserve dependency/security checks already required by the existing process when consolidating the workflow. Generated files and lockfiles must match the selected commit; unexpected changes fail the candidate.

Build all required artifacts using that commit and intended version. Capture the host archive, SHA256SUMS, reviewed release notes, topology manifest, and immutable agent image digest. If a host container image remains a supported distribution, require it as part of the same candidate.

The archive must include the binaries, updater scripts, and installation information its consumers need. Keep the candidate's full commit ID and artifact identities in the release record. Verify that the packaged version and recorded commit match the selected candidate.

Pin deployable images by digest. Mutable tags such as latest are conveniences, not deployment identity. Preserve all candidate artifacts and evidence in durable private storage.

3. Deploy to staging and run QA

Use the exact archive and image digests produced in stage 2. Follow the staging QA plan, including fresh install, upgrade, useful work, recovery, and release-specific scenarios.

A failure retains evidence and blocks progression. Retry infrastructure failures against the same candidate artifacts. Code changes require a new candidate. Do not rebuild validated binaries during promotion.

4. Approve deployment

Present Sam with the QA result, included changes, known limitations, migration requirements, and recovery procedure. Approval names the exact candidate and artifacts.

Use the CI system's supported approval mechanism, or a restricted manual promotion trigger. Do not assume Gitea's deployment-environment semantics match GitHub's. Only an approved candidate can obtain the authority to deploy to production.

5. Deploy through automation

Allow only one production promotion at a time. Verify the candidate identity and production's starting state immediately before installation. Respect work-in-flight checks, graceful shutdown, and the existing journaled updater.

Automation downloads authenticated artifacts, verifies checksums, pulls the pinned image, installs, restarts, and records progress. Installation follows one documented procedure in staging and production. A failed command must leave a diagnosable state and a safe retry or recovery action.

6. Verify production

Confirm that every required service reports the intended version and the configured agent image matches the approved digest. Check service health and complete a bounded real workflow using a designated test event/repository/channel.

Observe the updater's health window and retain deployment logs. Choose and document any additional observation period based on normal workload frequency. Confirm accepted work remains accounted for. A startup check alone is not enough.

On failure, stop promotion, execute the rehearsed recovery procedure, and record the outcome. Schema-changing recovery follows the release's explicit database procedure; do not assume swapping binaries restores database compatibility.

7. Publish stable and close the release

After production verification, mark the candidate's release as stable/published and advance any stable aliases to the same tested artifacts. Verify release metadata, authenticated downloads, checksums, and update discovery.

Record the deployment outcome in the release issue, associate delivered implementation issues, and close the release issue. If final publication fails after deployment succeeds, record that partial state and retry publication without reinstalling or rebuilding.

Release issue template

Title: Release <version>

Purpose and included changes:
Candidate commit and tag:
Starting production version:
Pipeline run:
Host archive checksum:
Agent image digest:
Other required artifact identities:

Source gate:
Full test suite:
Fresh install QA:
Upgrade QA:
Representative workflow QA:
Channel and settings QA:
Recovery rehearsal:
Release-specific QA:

Known limitations and acceptance:
Schema/config/topology changes:
Recovery procedure:
Approval by Sam for this candidate:

Deployment result:
Production versions and digest:
Production workflow verification:
Observation result:
Stable publication/update-discovery result:
Evidence links:

Measure the process

For each release, record validation, build, staging QA, deployment, and verification duration; failed stage; retry count; manual repair time; and whether production recovery was required.

Review these results after several releases. Optimise the stages that actually dominate time or fail repeatedly. Keep check definitions centralised, build artifacts once, and prefer small release scopes that make failures easier to identify.