Commit Chart.lock and use helm dependency build in your pipeline. It reconstructs the charts directory to the exact state in the lock file, without renegotiating versions. helm dependency update re-resolves, which is how two clusters end up with different subcharts.
Two commands, two behaviors
The Helm documentation describes helm dependency build as building out the charts directory from the Chart.lock file. It reconstructs a chart's dependencies to the state specified in the lock file, and it does not re-negotiate dependencies the way helm dependency update does. One detail matters: if no lock file is found, build mirrors the behavior of update.
So a missing lock file turns a safe command into an unsafe one without any warning. Keep the file in version control.
Why this matters across environments
A chart often declares dependencies by version range. If dev runs update on Monday and prod's pipeline runs update on Friday, a newer subchart release can slip into prod. That subchart can ship its own container images, defaults, and templates. You tested one combination and deployed another.
| Command | Reads lock file | Changes versions |
|---|---|---|
| helm dependency update | Re-resolves from Chart.yaml | Yes, within ranges |
| helm dependency build | Yes | No |
A pipeline recipe
- A developer changes Chart.yaml dependencies and runs update locally.
- They commit both Chart.yaml and Chart.lock in the same pull request.
- Reviewers read the lock diff, just as they would for a package lockfile.
- CI and every deploy job run build, never update.
- Fail the job if Chart.lock is missing.
Verify what the chart brings in
The lock file tracks chart versions. It does not tell you which container images those charts deploy. After rendering, list the image references and record their digests. A subchart upgrade can change an image without any change in your own values. See Docker tag or digest for pinning those.
Build also has verification flags. The docs list a verify option that checks packages against signatures, along with a keyring option. If your chart sources publish signatures, using it adds integrity to consistency.
What to review in a lock diff
- A version bump for any subchart, especially a major one.
- A changed repository URL. Treat that as a change of trust.
- A changed digest value, if present, with no version change.
Rehearse it once
Run a quick experiment in a scratch directory. Run update, commit the lock, then delete the charts directory and run build. Confirm the versions are unchanged. Then remove the lock file and run build again, and watch it behave like update. Seeing the difference once makes the rule easy to enforce in review.
Teams that deploy the same chart to several clusters should also record which Chart.lock revision each cluster runs. A short table in your release notes is enough, and it turns a vague question about subchart versions into a lookup.
What Safeguard does here
Safeguard scans container images and dependency files, and tracks findings over time, which helps when a chart upgrade changes what runs in a cluster. Try the free scan at gold.safeguard.sh/scan.
Quick check
Should Chart.lock be committed?
Yes for applications you deploy. It is the record that makes builds repeatable.
Does Chart.lock pin container images?
No. It pins chart dependencies. Pin images separately by digest.
Sources
Last reviewed: 19 October 2026.
