Q: How do you manage Helm chart versioning in CI/CD?
Helm chart versioning in CI/CD means treating the chart as its own artifact: version in Chart.yaml is the chart's SemVer and changes whenever templates or defaults change, while appVersion describes the application it deploys.
Want to master this scenario in a live sandbox? KodeKloud's Enterprise GitOps with ArgoCD & Kubernetes Rollouts covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: <strong>Helm chart versioning</strong> in CI/CD means treating the chart as its own artifact: <code>version</code> in <code>Chart.yaml</code> is the chart's SemVer and changes whenever templates or defaults change, while <code>appVersion</code> describes the application it deploys. CI packages the chart with explicit versions, pushes it to an OCI registry or chart repository as an immutable release, and environments pin the exact chart version. Interviewers ask to see whether you understand the two version fields, SemVer rules for chart changes, and how to avoid overwriting released versions.
Mental model: chart version versus appVersion
These fields change for different reasons and must not be confused. Keeping them separate lets you ship a chart-only fix, such as a new probe default, without pretending the application changed.
- version: Required SemVer 2 version of the chart. Bump it for any chart change: templates, values defaults, dependencies.
- appVersion: Informational version of the app, typically the image tag. It does not affect Helm's version resolution.
- SemVer meaning: Major for breaking changes to values or behaviour, minor for backward-compatible features, patch for fixes.
- Dependencies: The
dependenciessection pins subchart version ranges;Chart.lockrecords the resolved versions for reproducible builds. - Chart.yaml example:
apiVersion: v2,name: my-app,version: 1.8.0andappVersion: "1.5.0"; quote appVersion so YAML treats it as a string.
Hands-on: Helm chart versioning in CI
Package with versions injected from the pipeline and publish to an OCI registry (Helm 3.8 and later supports OCI by default). Because the pipeline injects the versions, nobody edits Chart.yaml by hand and the published artifact always matches the build that produced it.
helm dependency update charts/my-app
helm lint charts/my-app
helm template my-app charts/my-app -f values-prod.yaml > /dev/null
CHART_VERSION=1.8.0
APP_VERSION=1.5.0 # image tag built earlier in the pipeline
helm package charts/my-app --version $CHART_VERSION --app-version $APP_VERSION
# Successfully packaged chart and saved it to: my-app-1.8.0.tgz
echo "$REGISTRY_PASSWORD" | helm registry login registry.example.com -u ci --password-stdin
helm push my-app-1.8.0.tgz oci://registry.example.com/charts
- Lint and render:
helm lintandhelm templatevalidate before packaging. - Package with explicit versions:
--versionsets the chart version and--app-versionsets appVersion, overriding the file. - Authenticate and push:
helm registry loginthenhelm pushtooci://. - Install a pinned version:
helm install my-app oci://registry.example.com/charts/my-app --version 1.8.0. - Verify the artifact: After pushing,
helm pull oci://registry.example.com/charts/my-app --version 1.8.0andhelm show chartconfirm the published content matches what CI built.
Automate version bumps and promotion
Choose one deterministic rule so humans do not edit versions by hand.
# Argo CD Application (excerpt)
# source:
# repoURL: registry.example.com/charts
# chart: my-app
# targetRevision: 1.8.0
helm show chart oci://registry.example.com/charts/my-app --version 1.8.0 | grep -E 'version|appVersion'
- Tag-driven: Push a git tag like
chart-1.8.0and let the pipeline derive the chart version from it. - Conventional commits: Tools such as release-please can compute the next SemVer from commit types for charts and apps.
- Pre-releases for branches: Publish
1.8.0-rc.1or1.8.0-pr123.1for testing; SemVer orders these before the final release. - Promotion: Environments reference the version in GitOps, for example Argo CD
targetRevision: 1.8.0on the chart source, and promotion is a pull request changing that value. - Monorepo charts: When several charts share a repo, trigger versioning only for changed paths so unrelated charts do not receive empty releases.
Failure modes and edge cases
The common bugs are overwritten versions and version drift. Each of these is cheap to prevent in CI and expensive to untangle after clusters have pinned the wrong content.
- Republished version: Overwriting
1.8.0breaks clusters that cached or pinned it and makes audits impossible. Block re-push in CI by checking the registry first. - Forgetting to bump: Changing templates without bumping
versionmeans CI publishes nothing new or collides. Enforce with a CI check on chart path changes. - Plus signs in OCI tags: SemVer build metadata using
+is converted to_for OCI tags, which surprises people comparing versions. - Floating ranges: Subchart ranges like
^1.2.0drift unless you commitChart.lockand runhelm dependency build. - CRDs: Helm does not upgrade files in the
crds/directory onhelm upgrade, so chart version bumps that change CRDs need a separate, documented upgrade step.
Production practice
Make chart releases auditable and safe. The aim is that anyone can answer which chart version is running in each environment, and why, from Git history alone.
- Immutable registry settings: Enable tag immutability for the chart repository where supported.
- Sign charts: Use cosign on OCI chart artifacts or Helm provenance files with
helm package --sign. - Test upgrades: Run
helm upgrade --installfrom the previous released version in a kind cluster and validate withhelm test. - Document breaking changes: A major bump should come with migration notes and a values schema (
values.schema.json) to fail fast on bad input. - Rollbacks:
helm rollback my-app <revision>restores a previous release revision in the cluster, while pinning an earlier chart version in Git is the durable rollback in GitOps.
- Helm chart versioning treats the chart as a SemVer artifact where version tracks chart changes and appVersion tracks the application.
- I verify with helm lint, helm template, helm show chart on the published version and an upgrade test from the previous release.
- I automate bumps from tags or commit history, push to OCI with immutable versions, and pin versions in Argo CD.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Treating appVersion as the chart version Helm resolves charts by version, so bumping only appVersion creates confusion and collisions.
- Republishing an existing chart version Clusters and audits can no longer rely on the version to identify content.
- Leaving dependency ranges without Chart.lock Subcharts drift between builds and break reproducibility.
- Changing values defaults in a patch release It breaks consumers who rely on SemVer to signal compatibility.