Skip to content

Spec CI CD and Release

MAVERICK edited this page Nov 13, 2026 · 7 revisions

Spec: CI/CD and Release

Part of the Technical Specification. Requirement prefix: REL. Tools are named on Development Process; this page states the required behaviour. Which checks run and block at each stage (pre-commit, pull request, main, nightly, weekly, release), and the testing view of these environments, are on Test Environments and Quality Gates; the per-release test evidence is the test completion report of Test Documentation Templates (TST-019). The production API is never a test target (TST-010).

1. Pipeline

flowchart LR
  PR[Pull request] --> CI[Required checks]
  CI --> M[Merge to main]
  M --> B[Build image once,<br/>SBOM, signature, provenance]
  B --> D[Deploy to dev<br/>automatic]
  D --> S[Deploy to staging<br/>automatic on a release tag]
  S --> G{Staging gates:<br/>smoke, contract, load,<br/>overload, security scan}
  G -->|pass| C[Canary in prod]
  G -->|fail| X[Stop, fix forward]
  C --> W{Canary SLIs within budget<br/>for the observation window}
  W -->|yes| P[Full production]
  W -->|no| R[Automatic rollback]
Loading

2. Environments

Environment Purpose Data Keys Deployed
Local development fixtures in a throwaway database generated test keys on demand
CI checks fixtures generated per push
Dev integration of main fixtures vf_test_ each merge
Test stack performance, resilience, chaos and full DAST runs, isolated from production the benchmark fixture profile generated per run per nightly or weekly run
Staging the confirmed release's digest, production-shaped a production-shaped fixture set, never live production data unless the licence review allows it vf_test_ each confirmed release
Sandbox public test instance for clients fixtures vf_test_ issued to clients with each release
Production the public API the read contract vf_live_ after staging gates

3. Versions, notes and changelog

ID Requirement Verification
REL-001 Releases MUST be versioned with Semantic Versioning 2.0.0 and tagged vX.Y.Z on main; the version MUST be derived from Conventional Commits and kept in step with the platform version where the version-sync rule applies ([[Development Process Development-Process]]).
REL-002 Each release MUST publish release notes and a CHANGELOG.md section in Keep a Changelog 1.1.0 form (Added, Changed, Deprecated, Removed, Fixed, Security), listing every interface change with its requirement ids. Lint
REL-003 Each release MUST publish, under the same version: the image digest, the SBOM, the provenance, the OpenAPI document and the documentation build. Ops
REL-004 The same image digest MUST be promoted from staging to production; nothing is rebuilt between environments (Twelve-Factor V, build, release, run). Ops
REL-015 A release tag and every published image MUST come from a commit on which the required CI checks (unit and handler tests, integration tests, the coverage gate) completed with success; the publishing workflow MUST verify this itself before it tags, signs or pushes, and a missing, queued, running or failed check MUST be a refusal. Images MUST be published for confirmed releases only (an annotated vX.Y.Z tag equal to version.txt, never re-tagged); a push to main and a release candidate MUST publish none. Lint

4. Progressive delivery and rollback

ID Requirement Verification
REL-005 Production deployment MUST be progressive: a canary instance or a weighted share (design 10 %) for an observation window (design 15 minutes), then the rest. With a single instance, a blue-green switch with a health-gated cut-over and the previous release kept warm replaces the canary. Ops
REL-006 The canary MUST be judged automatically on error rate and latency SLIs against the previous release; a breach MUST roll back without human action. Ops
REL-007 Rollback to the previous release MUST be one command, complete within 5 minutes (design target), and never require a data migration to be reverted. Ops
REL-008 Access-store schema migrations MUST be backward compatible for one release (expand, migrate, contract), so that rollback is always safe. Review
REL-009 Every deployment MUST record version, digest, environment, actor and instant, and the operator dashboard MUST show deploy markers. Ops

5. Feature flags

ID Requirement Verification
REL-010 Unfinished operations MUST be hidden behind configuration (endpoints.disabled) or a per-key beta opt-in (VER-007), never behind undocumented parameters. Review
REL-011 Flags MUST be configuration keys with an owner and a removal date; a flag older than its removal date fails a lint. Lint
REL-012 A flagged-off operation MUST answer 404 feature-disabled and be absent from the served OpenAPI document (FR-GEN-006). Handler

6. Delivery metrics (DORA)

Metric Design target for the first year
Deployment frequency on demand, at least weekly when changes exist
Lead time for changes (merge to production) under one day
Change failure rate under 15 % of deployments need a rollback or hotfix
Time to restore service under one hour
ID Requirement Verification
REL-013 The four DORA metrics MUST be computed from the deployment record and incident log and reviewed at each minor release. Ops
REL-014 CI time to a green pull request SHOULD stay under 15 minutes with a warm cache. Ops

7. Required checks and the release pull request

Branch protection on main requires a pull request, linear history and resolved conversations, refuses force pushes and deletion, binds administrators, and requires the branch to be up to date with main and these checks to pass:

Workflow Required checks
CI Lint, Unit and handler tests, Integration tests (PostGIS), Coverage gate (100 % per package), Generated files are current, OpenAPI lint and breaking changes, govulncheck, Image (build, lint, scan, healthz), Compose smoke (Schemathesis), SonarCloud analysis, Requirement report
Security CodeQL (Go), Secrets in history (gitleaks), Snyk (dependencies), Dependency review, Dependency licences, DAST (OWASP ZAP against the compose stack)
(removed) Semgrep, OSV-Scanner, Trivy (repository) and Checkov (Dockerfile, workflows) left the required set with the one-tool-per-check decision of 2026-11-08 ([[Spec: Secure SDLC and Supply Chain
SonarCloud SonarCloud Code Analysis

The required approving-review count is 0: every pull request is opened from a maintainer's account, so a count of 1 would make the other maintainer's approval mandatory on each one. The review is the maintainer's verdict comment on the pull request's head commit (Development Process). Each check was proved once to turn a pull request red, on a throwaway branch with a planted lint error, a failing test and a breaking OpenAPI change.

The release pull request. After CI passes on a push to main, release-please opens or updates the release pull request with the built-in workflow token (the repository allows GitHub Actions to create pull requests; no personal token is used). GitHub holds the pull request's CI and Security runs for approval because a bot opened it, and branch protection reads only pull-request runs, so the same job approves those runs and fails when either workflow has no run on the head commit. Merging the release pull request makes release-please write a draft release; the tag job then creates the annotated tag only after the CI gate of REL-015 has passed on the release commit.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally