CI/CD and Releases
This page is the map for the repo's CI/CD flow: prebuild artifacts, the canary main tag, RC/hotfix tags, and final releases.
The Release Ladderβ
Every image and Helm chart carries the same tag, so you can tell how stable a build is just by looking at it. RCs and hotfixes both graduate into a final release using the same steps β see Final Release Flow below.
| Tag | Stage | Created from | Meaning |
|---|---|---|---|
canary | Alpha | every merge to main | Always the newest main build. Gets replaced on every merge β don't rely on it staying the same. |
x.y.z-rc.N | Beta | every push to release/x.y.z | A release candidate. Fixed β never changes once created. |
x.y.z-hotfix.N | Beta (patch) | every push to release/x.y.z-hotfix | A candidate fix for a version that already shipped. Fixed β never changes once created. |
x.y.z | Stable | release-manual.yml | The production release. Also tagged latest. Fixed β never changes once created. |
Chart version and image tag always match β with one exception. Helm requires a chart's version field to be strict SemVer, and canary isn't, so the canary chart is packaged as 0.0.0-canary instead. Its appVersion still reads canary, so it still deploys the matching canary images by default.
Artifact Locationsβ
| Artifact type | Flow | Registry path |
|---|---|---|
| Docker images | all release and prebuild flows | ghcr.io/caipe-io/<image> |
| Helm charts | all release and prebuild flows | ghcr.io/caipe-io/charts |
PR Flowβ
pr-version-bump.yml runs on every PR targeting main or release/**:
- Checks whether the PR branch contains the latest base branch and whether GitHub reports merge conflicts, posting an update comment and failing the check if not.
- Applies a PR flow label such as
dev,0.4.0,0.4.0-hotfix, orrelease/0.4.0. - For a
release/x.y.z -> mainPR specifically, uses.github/actions/prepare-release/action.ymlto commit the finalx.y.zversion files and changelog onto that PR branch ahead of merge.
Ordinary PRs get no commit β prebuild and canary tags are worked out fresh at build time instead of being written into the repo.
Docker and Helm Image CIβ
Every image and chart workflow (ci-*.yml, ci-helm.yml β see the reference table below) triggers on two ref shapes:
- Push to
mainβ buildscanary, but only for the component(s) whose own paths actually changed in that push. A docs-only or single-component merge does not rebuild everything. - Push of a tag (
x.y.z,x.y.z-rc.N,x.y.z-hotfix.N) β builds every component fresh, regardless of which paths changed. This is what makes an RC or final release a complete, reproducible artifact set.
Each workflow figures out its own tag via .github/actions/determine-release-tag/action.yml: canary for a main push, the pushed tag for a tag push, or whatever you typed in if you triggered the build by hand.
Only a resolved stable x.y.z version also receives the latest image alias.
This applies to manual builds too: an RC/hotfix input never updates latest, and
a manual main build without a version publishes canary.
Every Docker metadata step explicitly sets flavor: latest=false, including
prebuilds and manifest merges. Docker's default automatic Latest generation for
tag refs must stay disabled; the explicit stable-only raw tag rule controls the
release alias. Keep existing variant suffixes alongside this setting.
Prebuild Artifactsβ
Prebuild artifacts let you test Docker images or Helm charts from a PR before it merges, without waiting for an official tag.
- Create a branch called
prebuild/*, for exampleprebuild/feat/add-feature-a. - Open a PR from the prebuild branch to the intended target branch.
- Each
prebuild-*.ymlworkflow triggers directly off that PR and publishes only the component(s) whose paths changed, tagged<latest-stable-tag>-<branch>-<N>β for example1.1.0-feat-add-feature-a-3, where1.1.0is the latest stable release and3is the commit count on the branch. - Each new commit increments
Nand publishes a new tag. prebuild-image-cleanup.ymldeletes every tag for that branch once the PR merges or closes.
Release Candidate & Hotfix Flowβ
Use a release/x.y.z branch to prepare a new release, or release/x.y.z-hotfix to patch an already-released version β the flow is identical either way:
- Create or update the branch.
- Open PRs targeting it and merge them.
auto-tag.ymlcreatesx.y.z-rc.N(orx.y.z-hotfix.N) on every push to the branch.- The tag push triggers Docker and Helm CI for every component.
- Test the published artifacts from GHCR.
When ready to publish, run the final release flow below with the intended final semver tag.
To build an RC on demand, use the prerelease workflow:
gh workflow run release-prerelease.yml -f release_branch=release/1.4.0
RC builds publish image and chart artifacts, then release-finalize.yml creates a
GitHub Pre-release after every required tag-push build succeeds at the tag's
exact commit. RC notes show changes since the previous reachable RC in the same
series (or the preceding reachable stable tag for the first RC), a full comparison
against that stable tag, and exact Helm/image installation commands. RCs require
no release blog and never update CHANGELOG.md or the latest image alias.
Hotfix test tags, canary, and dev builds remain artifacts only.
Manual promotion must run from main (--ref main); other dispatch refs are
rejected before release credentials or version files are touched. Hotfix branch
merge-backs skip stable preparation and automatic promotion. Older-series stable
maintenance releases are currently unsupported; merge the tested fix into main
and select a stable version newer than the latest stable tag.
Retain RC Git tags after a stable release so their original commits remain
available from the Tags tab.
Final Release Flowβ
Final releases use plain x.y.z tags and are always cut manually:
- Open a PR from
release/x.y.ztomain.pr-version-bump.ymldetects the release merge and commits the final version files and changelog onto that PR branch. - Merge the release PR to
main.auto-tag.ymldetects the merge and dispatchesrelease-manual.yml. release-manual.ymlvalidates the stable version β a plainx.y.zstrictly greater than the latest stable tag β then creates the final tag, pushes it, and creates a draft GitHub Release. The same workflow accepts increasing RC/hotfix inputs for candidate builds; RC publication follows the separate pre-release policy above.- The tag triggers Docker and Helm CI for every component; each notifies
release-finalize.ymlon completion. release-finalize.ymlpublishes the draft once all required workflows pass, then dispatches post-release security scanning and sanity tests. It retains existing RC Git tags.
If a required workflow fails, the stable release stays a draft with a failure note for investigation. Stable publication also waits for the canonical release-blog URL to become reachable; RC publication does not depend on a blog.
Changelog Policyβ
- Keep one
CHANGELOG.mdsection per stable release. - Fold dev, RC, and hotfix changes into the next stable release using Commitizen's
changelog_merge_prereleasesetting. Ignore prerelease tag boundaries so an RC-tagged HEAD also generates the requested stable heading. - Update incrementally so published history survives even if historical tags were
removed.
prepare-releasepasses--incremental --merge-prereleasewhen generating the next stable entry. - RC change sets live in GitHub pre-release notes; they do not create stable changelog sections. The stable release rolls up all changes since the preceding stable release regardless of RC publication. Stable GitHub Release notes also explicitly start at the preceding stable tag, so published RCs cannot shorten the generated change set.
Useful Workflow Referenceβ
| Workflow or action | Responsibility |
|---|---|
.github/workflows/pr-version-bump.yml | PR labels, branch freshness checks, release/*βmain version preparation |
.github/workflows/auto-tag.yml | Detects release-branch merges to main; creates -rc.N/-hotfix.N tags on release branch pushes |
.github/workflows/release-manual.yml | Validates stable/RC/hotfix promotion from main; only stable promotions create a draft GitHub Release |
.github/workflows/release-prerelease.yml | Manually cuts an -rc.N/-hotfix.N tag on demand |
.github/workflows/release-finalize.yml | Publishes stable drafts or RC pre-releases after required CI workflows pass |
.github/actions/publish-rc-release/action.yml | Generates explicit RC delta/full comparison notes and exact install commands; publishes with prerelease=true, latest=false |
.github/workflows/ci-*.yml | Publishes canary on main pushes, and every tag on tag pushes |
.github/workflows/ci-helm.yml | Publishes the Helm chart the same way |
.github/workflows/prebuild-*.yml | Publishes temporary prebuild images and charts for PR testing |
.github/actions/prebuild-version/action.yml | Computes <latest-stable-tag>-<branch>-<N> for prebuild builds |
.github/actions/validate-release-tag/action.yml | Requires stable semver for final releases; validates RC/hotfix series on release branches |
.github/actions/update-version-files/action.yml | Sets version + appVersion + local dependency refs across pyproject, lockfile, and every chart |
.github/actions/determine-release-tag/action.yml | Resolves the tag used by image and chart CI workflows (canary, a pushed tag, or a manual input) |
.github/actions/prepare-release/action.yml | Updates final release files and generates changelog |
Troubleshootingβ
- PR check fails with a branch update comment β merge the latest target branch into the PR branch and push again.
- A
canarybuild didn't pick up your change β check whether your component's own paths actually changed in that push; a main push only rebuilds affected components, not everything. - A final release stays as a draft β inspect the required CI workflows listed in
release-finalize.yml. It publishes only after all required workflows pass or are skipped successfully.