Repository navigation
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).
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]
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
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.
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference