Why promote a packaged, version-pinned Helm chart instead of upgrading from the branch checkout?

## What identifies a chart `Chart.yaml` carries two version fields and they answer different questions. `version` is the SemVer of the **chart artifact** — the templates, defaults and dependency set — and it is what `helm package` puts in the tarball name, what a repository indexes, and what `--version` selects. `appVersion` is a free-form string naming the **application** the chart deploys; it is informational, and the scaffolded image line reads it as a fallback tag (`{{ .Values.image.tag | default .Chart.AppVersion }}`). Promotion is about the first of these: moving one chart version across environments. ## Why a directory is not an artifact `helm upgrade fraud-platform ./charts/fraud-platform` is legal and convenient, and it is what makes environment drift invisible. The chart it installs is whatever that working tree contained at that instant. If staging deployed at 09:10 and production at 15:40, every merge in between is in production and was never in staging — not as a values change anyone reviewed, but as template changes nobody attributed to the deploy. Dependencies make it worse: if the deploy job runs `helm dependency update` first, subchart versions are re-resolved against whatever the constraint in `Chart.yaml` allows now, so an umbrella chart bundling a fraud-scoring API and a worker can acquire a new worker subchart on the production deploy alone. ## Package once, promote the same version `helm package charts/fraud-platform` produces `fraud-platform-1.7.3.tgz` — for this chart about 3.4 MB, because `charts/` contains the two subchart tarballs that `helm dependency update` resolved and `Chart.lock` recorded. That tarball is the unit of promotion. Push it once, then install it into each environment by version: ```bash helm upgrade --install fraud-platform \ oci://registry.example.com/charts/fraud-platform --version 1.7.3 \ -n fraud-prod -f values/prod.yaml ``` Now exactly two things vary across environments: the values file, and *when* each environment got the version. That is what makes staging meaningful — staging is not merely similar to production, it ran the same chart. ## Verifying a promotion Because Helm records the chart a release was installed from, promotion is auditable after the fact. `helm list -n fraud-prod` shows a CHART column reading `fraud-platform-1.7.3`, `helm history` shows the chart version at every revision, and `helm get metadata` reports the chart name, version and appVersion for the current release. Comparing those three environments is a five-second check that no amount of pipeline logging replaces. `--version` accepts a constraint as well as an exact tag, and that is worth refusing on a promotion path. `--version '^1.7.0'` resolves at deploy time against whatever the repository holds then, which reintroduces precisely the drift that packaging removed: staging resolves 1.7.3 in the morning and production resolves 1.8.0 in the afternoon. Promotion means an exact version, written down, that a human can read in the deploy log. ## Immutability is not free Helm does not by itself stop a version being republished with different contents: a classic repository is an `index.yaml` pointing at tarballs, and whoever can write the tarball can replace it. Get immutability from the repository or registry that stores the chart, keep the tarball you tested rather than rebuilding it per environment, and if you need cryptographic assurance, `helm package --sign` writes a `.prov` file beside the `.tgz` that can be verified at install. Signing charts is opt-in, so nothing happens unless you ask for it. ## Two axes, one at a time There are two independent things that can move during a deploy: the chart version, and the values. A clean promotion moves the chart version and leaves the environment file alone; a configuration change moves the file and leaves the version alone. Moving both in the same production window is the reason so many incident reviews cannot say whether the chart or the config broke it. Where the application image tag lives is the same question in miniature: if the tag is a per-environment value, promoting the chart does not promote the application, and you have two promotion paths to keep in step. Many teams instead let the chart's `appVersion` supply the default tag, so the application version travels inside the chart artifact and one promotion moves both. ## The practical rule Build the chart once, on merge or on tag; deploy that version to dev; deploy the same version to staging; deploy the same version to production. If any environment is deploying from a path on disk rather than a version from a repository, the word 'promotion' is not describing what is happening.