Bump version whenever anything in the chart changes, including templates and defaults. Bump appVersion when the application the chart deploys changes. They are independent. Helm uses version for chart identity and treats appVersion as informational only, so a template fix needs a new chart version even when the app is unchanged.
What the Helm docs say
Helm's chart documentation says version must be set on every chart and should follow SemVer 2, though that is not strictly enforced. Non SemVer names are rejected, except forms like x or x.y, which Helm coerces to full SemVer, so v1.2 becomes v1.2.0.
appVersion describes the version of the application the chart contains. The docs state it is unrelated to version, is informational only, and does not affect chart version calculations. Quoting it is recommended.
Which change needs which bump
| Change | version | appVersion |
|---|---|---|
| New app release, same templates | Patch or minor | Yes |
| Template fix, same app | Patch | No |
| New optional value with safe default | Minor | No |
| Rename or remove a value | Major | No |
| Change a default that loosens security | Major | No |
| Raise kubeVersion floor | Major or minor, state your rule | No |
A chart is shared infrastructure. Its interface is the values file and the objects it renders. Treat changes to either as the thing SemVer tracks.
Why shared charts are strict about this
Consumers pin a chart by version. If you change templates and forget to bump it, two people can have the "same" chart version with different behaviour. For a security default, that is how a quiet regression reaches production.
Consumers should also install by digest where possible, so what they deploy matches what was reviewed. See installing a chart by digest from an OCI registry.
Process steps
- Decide whether the change touches templates or values. If yes,
versionbumps. - Decide whether the application image changed. If yes, update
appVersiontoo. - Classify the bump with the table above and record breaking changes in release notes.
- Make a reviewer verify the bump, since a missing one is easy to miss. A required check that compares
Chart.yamlin the pull request against the base branch can catch it. This is a convention you build, not a Helm feature. - Publish only from the reviewed commit.
Common mistakes
- Using
appVersionas the chart version. Consumers then cannot tell a template change from an app change. - Leaving
appVersionunquoted. Helm recommends quoting it. - Treating a default change as a patch. Anything that alters rendered objects for existing users can break them.
Related fields
apiVersion: v2 is for charts that require Helm 3 or later. It moved dependencies into Chart.yaml and added the type field. Dependencies are a list of name, version and repository, downloaded by helm dependency update. See bumping a chart dependency and the lock file.
Where Safeguard fits
Safeguard's policies and gates can hold a pull request until required checks and reviewers pass, and its SBOM and dependency scanning covers what your repositories declare. The bump rules are your convention.
Quick check
Does appVersion affect which chart Helm installs?
No. Helm's documentation says it is informational and does not affect chart version calculations.
Must version follow SemVer?
The documentation says it should follow SemVer 2 but is not strictly enforced, and non SemVer names are rejected apart from the x or x.y forms it coerces.
Sources
Last reviewed: 19 October 2026.
