Release Process

This document is for Distro team maintainers. For contribution process, see the Maintainer Guide.

The charts are built, linted, and tested on every push to the main branch. The release process follows a 3-stage pipeline that ensures the exact artifact tested by QA is what gets publicly released — no rebuilding at release time.

Architecture Overview

┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
│  1. DEV BUILD       │     │  2. RC PROMOTION    │     │  3. QA GATE         │     │  4. PUBLIC RELEASE  │
│  (Every merge)      │ ──► │  (Manual trigger)   │ ──► │  (External)         │ ──► │  (Manual trigger)   │
├─────────────────────┤     ├─────────────────────┤     ├─────────────────────┤     ├─────────────────────┤
│ • Build dev package │     │ • Retag dev → RC    │     │ • QA validates RC   │     │ • Pull RC from      │
│ • Push to Harbor    │     │ • Create release-   │     │   from Harbor       │     │   Harbor            │
│ • Cosign signing    │     │   please PR         │     │ • Sign-off required │     │ • Publish to GitHub │
└─────────────────────┘     └─────────────────────┘     │   before Stage 4    │     │   Releases          │
        ↓                           ↓                    └─────────────────────┘     │ • Cosign signing    │
   Harbor (internal)          Harbor (retag only)                  ↓                 └─────────────────────┘
   {version}-dev-{sha}        {version}-rc               QA approval required                  ↓
                                                                                       GitHub Releases
                                                                                       helm.camunda.io

Registries

Registry	Purpose	Access
Harbor (registry.camunda.cloud/team-distribution)	Internal dev/RC storage	Internal only
GitHub Releases (helm.camunda.io)	Public releases	Public

Release Pipeline

Stage 1: Dev Package Build

Workflow: chart-build-dev.yaml

Trigger: Automatic on every merge to main (for paths: charts/camunda-platform-*/**).

What happens:

1. Builds dev packages for all chart versions selected by chartAutomation.routineVersions.
2. Computes the release version using release-please --dry-run.
3. Applies release transformations (removes dev comments, badges).
4. Generates release notes using the release-tools release-notes command.
5. Packages the chart with the final release version in Chart.yaml.
6. Pushes to Harbor with dev tags.
7. Signs with Cosign.

Tagging scheme:

Tag	Example	Purpose
{version}-dev-{sha}	13.4.0-dev-abc1234	Immutable, traceable to commit
{chart-major}-dev-latest	13-dev-latest	Rolling, always points to latest

Workflow summary shows:

• Package location and tags.
• All component image versions (from values.yaml).
• Cosign verification status.

Note: The Chart.yaml inside the package contains the real release version (e.g. 13.4.0), not the dev tag. This is computed via release-please dry-run at build time.

Stage 2: RC Promotion

Workflow: chart-promote-rc.yaml

Trigger: Manual workflow_dispatch with input:

• dev-tag: The dev package to promote (e.g. 13.4.0-dev-abc1234 or 13-dev-latest).

What happens:

1. Resolves rolling tags to actual dev tags via the Harbor API.
2. Validates the commit is on the main branch.
3. Runs release-please release-pr to create/update the release PR.
4. Adds RC tags to the same artifact in Harbor (no rebuild!).

Tagging scheme:

Tag	Example	Purpose
{version}-rc	13.4.0-rc	Immutable RC tag
{chart-major}-rc-latest	13-rc-latest	Rolling, always points to latest RC

Release-Please PR:

• Updates Chart.yaml version and changelog annotations.
• Updates .release-please-manifest.json.
• The promotion workflow generates the release files on the PR from the dev package: RELEASE-NOTES.md, the Chart.yaml release annotations, and the version matrix files (component versions mapping + READMEs).

Stage 3: Public Release

Workflow: chart-release-public.yaml

Trigger: Manual workflow_dispatch with input:

• rc-tag: The RC package to release (e.g. 13.4.0-rc or 13-rc-latest).

What happens:

1. Pulls the RC package from Harbor.
2. Extracts metadata (version, app version) from the packaged Chart.yaml.
3. Uploads to GitHub Releases using helm-cr.
4. Updates the Helm repo index (gh-pages branch).
5. Signs with Cosign and uploads the bundle to the release.
6. Stamps the published release's date onto the chart's version-matrix.json entry (release-tools stamp-release) and regenerates the matrix READMEs on the release-please branch — the single write of release_date, taken from the GitHub release's publishedAt.
7. Labels the release-please PR with autorelease: published.

Release tag format: camunda-platform-{appVersion}-{version} (e.g. camunda-platform-8.8-13.4.0).

After public release:

1. The workflow enables auto-merge on the release-please PR, then shepherds it through the merge queue (re-enabling auto-merge after evictions). If it still does not merge within the timeout, a distinct Slack alert pings the distribution release manager to merge it manually — the release itself is not treated as failed.
2. Merging the release-please PR syncs main with the released artifact and triggers chart-public-files.yaml to update:
   • Version matrix (component versions for each chart release).
   • Public values files at helm.camunda.io/camunda-platform/values/.

Helm-Only Ad-Hoc Release

Use this process when a Helm Chart fix is needed (e.g. incorrect image tag, chart misconfiguration) and no application components need to be re-released. It requests an ad-hoc release train scoped to HC (Helm Chart) only, rather than a full multi-component train.

When to Use

• A released Helm Chart contains an error (e.g. wrong image tag, misconfigured value).
• The fix is limited to the Helm Chart — no new application component versions are involved.
• A full multi-component release train would be overkill.

Steps

1. Make sure the fix is merged to main and a dev package was built — the post-merge build is automatic; manually trigger chart-build-dev.yaml only if it hasn't run yet, or if you need to pin specific component image versions rather than taking the latest.

2. Request the ad-hoc release train — In #top-c8-release-train, trigger the "Ad-Hoc Release Train Request" Slack workflow. Fill in:

   • Reason for the ad-hoc release (link the Jira/support ticket).
   • Which minor version(s) are included (e.g. 8.9).
   • Due date.
   • Released artifact — select HC (Helm Chart) only; do not select other components.

   Submitting posts a formatted announcement in the channel that pings the release train manager. This is a request, not a self-service trigger: the release train manager makes the final call and coordinates whether other components join. RC promotion, QA testing, the public release, and the release-please PR merge are all automated on your side and require no further manual action once the train is kicked off.

Notes

• Chart versioning: the release version is determined by the workflows — chart-build-dev.yaml derives the version from a release-please dry-run (falling back to the current Chart.yaml version), and chart-promote-rc.yaml forces --release-as to the version parsed from the selected dev tag.
• This process is for Self-Managed only — no SaaS rollout is involved.

Release Process Flowchart

Version Tagging Summary

Stage	OCI Tag	Chart.yaml Version	Registry
Dev	{version}-dev-{sha}	{version}	Harbor
RC	{version}-rc	{version}	Harbor
Public	N/A (GitHub Release)	{version}	GitHub Releases

Camunda version derivation: The Helm chart major version maps to a Camunda version:

• 11.x = Camunda 8.6
• 12.x = Camunda 8.7
• 13.x = Camunda 8.8
• 14.x = Camunda 8.9

Routine Chart Automation

chartAutomation.routineVersions in charts/chart-versions.yaml selects routine CI, dev packaging, artifact verification, and maintenance chores. Lifecycle metadata is independent and controls the existing version-matrix display. An ESUP case requires routine Helm chart automation only when its agreed delivery scope includes that maintenance; component-only cases can use explicit ad-hoc validation without joining the routine list.

Minor Version Chores

When Camunda releases a new minor version (typically every 6 months), the following changes are needed.

Assuming current alpha is 8.9 (which will become stable) and the new alpha is 8.10:

Before starting:

1. Label all existing PRs with backport-to-latest so contributors know their PRs need updating.

Chart files updates:

1. Copy charts/camunda-platform-8.9 to charts/camunda-platform-8.10.
2. Update chart version in charts/camunda-platform-8.9/Chart.yaml (remove alpha, e.g. 14.0.0-alpha5 → 14.0.0).
3. Update image tags in charts/camunda-platform-8.9/values-latest.yaml (no SNAPSHOT tags).
4. Update chart version in charts/camunda-platform-8.10/Chart.yaml (bump major, reset alpha, e.g. 14.0.0-alpha5 → 15.0.0-alpha1).

Configuration files updates:

1. Update charts/chart-versions.yaml — set released and stdSupportUntil in camundaSupportLifecycle for the minor becoming GA. The presence of released switches release tooling from prerelease to stable selection. Add the new alpha's lifecycle entry without released, and add it to chartAutomation.routineVersions. Reconcile routine membership against the ESUP Case Registry's Helm chart delivery scope; keep a minor in the routine list while that scope requires continued chart maintenance. Do not remove lifecycle dates when removing a minor from routine automation.
2. Update Release-Please config and manifest in .github/config/release-please/.
3. Update renovate.json5.
4. Update GitHub Actions with version choices (search for type: choice).
5. Update chart-release-snapshot.yaml with new chart paths.
6. Update pr-labeler.yaml.
7. Update docs/release.md examples.

Create a PR with the changes, and once merged, follow the normal release process.

Artifact Hub

The Camunda repo is configured on Artifact Hub. After a release, Artifact Hub automatically scans and indexes the new version.

Note: Charts may take up to 30 minutes to appear on Artifact Hub. After successful release, charts are immediately available via helm.camunda.io.

Troubleshooting

Dev package not found

If RC promotion fails because the dev package doesn't exist:

1. Check if the commit SHA is correct.
2. Verify the dev build workflow succeeded for that commit.
3. Check Harbor directly for available tags.

Release-Please PR not created

If the RC promotion workflow doesn't create a release-please PR:

1. Check for existing unmerged release-please PRs with the autorelease: pending label.
2. Verify there are releasable commits (conventional commit format required).
3. Check the release-please logs for errors.

Release already exists

If the public release fails because the release tag already exists:

1. Delete the existing release: gh release delete <tag> --yes.
2. Re-run the public release workflow.

Image version mismatch

Before promoting to RC, verify component image versions match the release train:

1. Check the dev build workflow summary for image versions.
2. Compare with the release train announcement (Slack/Tasklist).
3. If there's a mismatch:
   • Option A: Wait for Renovatebot to update and automerge.
   • Option B: Manually trigger chart-build-dev.yaml with specific image tag inputs (the workflow supports overriding individual component versions).
   • Option C: Manually create a PR to update values.yaml.

Related Workflows

Workflow	Purpose
chart-build-dev.yaml	Stage 1: Build dev packages
chart-promote-rc.yaml	Stage 2: Promote dev → RC
chart-release-public.yaml	Stage 3: Publish to GitHub Releases
chart-release-artifact-verify.yaml	Daily Cosign verification
chart-public-files.yaml	Update public docs after PR merge

Release Process Change Policy

Avoid surprises during releases by ensuring all release-affecting changes are communicated clearly and early.

Requirements:

• Communicate before the change goes live.
• Announce in #top-c8-release-train and CC:
  • @monorepo-release-manager
  • @qa-release-manager
  • Others if relevant