Skip to content

Release Process

MAVERICK edited this page Nov 13, 2026 · 4 revisions

Release Process

How a version of ViaFrei API gets from a merged pull request to a signed, verified image and a release page. The maintainer checklist is in the repository: docs/RELEASING.md. Implemented in milestone 0.2.0 (issue #5). Requirements: Spec: CI/CD and Release and Spec: Compatibility and Versioning.

The flow

flowchart TD
  PR[Pull request with a Conventional Commit title] --> CI{CI green and reviewed}
  CI -->|squash merge| MAIN[Push to main]
  MAIN --> RP[release-please opens or updates the release pull request]
  RP --> RPR[Release pull request: version.txt, manifest and CHANGELOG section]
  RPR -->|a maintainer merges it| DRAFT[release-please writes a draft release, no tag yet]
  DRAFT --> TAG[tag job creates the annotated tag vX.Y.Z]
  TAG --> REL[release.yml builds amd64 and arm64 and pushes by digest]
  REL --> SIGN[cosign signature, SLSA provenance and SBOM attestations]
  SIGN --> ASSETS[Assets: openapi.json, the OpenAPI diff, SBOMs and SHA256SUMS]
  ASSETS --> PUB[Notes get digest, tags and verify commands, draft published]
  PUB --> VER[verify job pulls by digest, checks signature, provenance, checksums and healthz]
  VER --> MS{Milestone X.Y.Z has open issues}
  MS -->|no| CLOSE[Milestone closed]
  MS -->|yes| LIST[Open issues listed in the job summary]
Loading

Rules

  • Versions come from commit titles. fix: is a patch; feat: is a minor; a breaking change (! or a BREAKING CHANGE: footer) is a minor before 1.0.0 and a major after. Every 0.x and every candidate is a GitHub pre-release.
  • Tags are annotated, never moved, never deleted. release.yml refuses a lightweight or malformed tag. Two live tag rulesets (their JSON is in docs/RELEASING.md) apply. One refuses to create or move a v* tag with any suffix (-…, +…), for everyone, with no bypass. The other refuses to move or delete any v* tag, with repository admins as the only bypass.
  • The draft comes first. release-please writes a draft release, which creates no tag; the workflow then creates the tag itself, so a tag never exists without the run that publishes it.
  • The OpenAPI diff is on every release page, against the previous release, so a breaking change is visible even where the version rules allow it.
  • Images exist for confirmed releases only. release.yml refuses a tag with any suffix, a tag that differs from version.txt, and a tag that is not on the commit that set version.txt (the release commit); a push to main publishes no image. GitHub refused two further rules here. A tag-name pattern rule needs an Enterprise plan; the suffix ruleset and release.yml's own refusals cover that. A creation restriction would also block release-please's tag, because a personal-account repository cannot list the Actions app as a bypass actor. So review of the release commit and the collaborators' trust are the boundary for who creates a plain vX.Y.Z tag. The image tags are X.Y.Z, X.Y and latest.
  • Release candidates publish nothing: no image and no release page. To try one, build it locally from its commit.

When something goes wrong

Situation What happens
A release is broken Rollback by redeploying the previous release's digest; the fix ships as a new patch. No tag is moved.
A fix cannot wait for main Hotfix branch from the tag; its first reviewed pull request brings the current release.yml from main (a tag push runs the workflow of the tagged commit); the fix lands in a reviewed pull request; another reviewed pull request bumps version.txt and the changelog to the patch version; a maintainer tags that commit; the fix is merged back to main with the manifest updated.
A release must be withdrawn Yank: the release page is titled [YANKED] with the reason and the replacement; the moving tags are pointed back at a good image; a security reason gets an advisory. The release is never deleted.

What a release needs

Item Used by Without it
SONAR_TOKEN (repository secret) CI SonarCloud analysis the job fails and names the secret
SNYK_TOKEN (repository secret) dependency scan the job fails and names the secret
"Allow GitHub Actions to create and approve pull requests" release-please no release pull request
The image package public and linked to the repository anonymous pulls pulls need a login

Before a release pull request is merged, CI must be green on it, including the image, compose, coverage (100 % per package, Testing Strategy) and requirement-report jobs.

See also: Container and Deployment · Development Process · Roadmap

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally