From 4333d804e7e09a2ffd5bc924cc9d2d84b9f4fa4f Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Wed, 15 Jul 2026 01:26:53 +0000 Subject: [PATCH 1/2] docs: document SOURCE_DATE_EPOCH for reproducible chart archives Add a how-to section explaining how to set SOURCE_DATE_EPOCH to produce reproducible chart archives with helm package, including value semantics and the scope of the four other commands that honor it. relates to helm/helm#32162 Signed-off-by: promptless[bot] --- docs/howto/charts_tips_and_tricks.md | 42 ++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/docs/howto/charts_tips_and_tricks.md b/docs/howto/charts_tips_and_tricks.md index 953bc7fac..518619029 100644 --- a/docs/howto/charts_tips_and_tricks.md +++ b/docs/howto/charts_tips_and_tricks.md @@ -309,3 +309,45 @@ existing release will be upgraded. ```console $ helm upgrade --install --values ``` + +## Build Reproducible Chart Archives + +By default, the files inside a packaged chart archive (`.tgz`) +carry the modification times of the source files on disk. +As a result, repackaging the same chart produces archives that differ from one build to the next. +To make chart archives reproducible, +Helm honors the `SOURCE_DATE_EPOCH` environment variable defined by the +[Reproducible Builds](https://reproducible-builds.org/docs/source-date-epoch/) project. +When you set it, +Helm stamps every file in the archive with the modification time you provide +instead of the build time. + +Set `SOURCE_DATE_EPOCH` to a Unix timestamp, +the number of whole seconds since 1970-01-01 in UTC, +and run `helm package`: + +```console +$ SOURCE_DATE_EPOCH=1609459200 helm package ./mychart +``` + +Helm stamps every file in the resulting archive with 2021-01-01T00:00:00Z, +so packaging the same source again produces the same timestamps. +To track your source history, +derive the timestamp from your last commit: + +```console +$ SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct) helm package ./mychart +``` + +Keep the following in mind when you use `SOURCE_DATE_EPOCH`: + +- The value must be a non-negative integer. + Helm interprets it as whole seconds in UTC and does not support sub-second precision. + A non-numeric or negative value fails the command with an `invalid SOURCE_DATE_EPOCH` error. +- When the variable is unset or empty, + Helm keeps the default behavior, + where archive entries reflect the actual file modification times. +- `helm install`, `helm upgrade`, `helm dependency build`, and `helm dependency update` + also honor `SOURCE_DATE_EPOCH`, + but only when they re-archive a dependency sourced from a local `file://` repository. + Helm stores remotely downloaded dependencies as it fetched them. From 9bfb79f3cf595e0d5c84aafe4e070ab3f7c5d57b Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Mon, 20 Jul 2026 10:57:54 +0000 Subject: [PATCH 2/2] docs: note Chart.lock generated timestamp is stamped by SOURCE_DATE_EPOCH Charts with a Chart.lock now produce byte-identical archives across builds when SOURCE_DATE_EPOCH is set, because the lockfile's generated: field is stamped with the same normalized (UTC, whole-second) timestamp. Refs helm/helm#32403, helm/helm#32396 Signed-off-by: promptless[bot] --- docs/howto/charts_tips_and_tricks.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/howto/charts_tips_and_tricks.md b/docs/howto/charts_tips_and_tricks.md index 518619029..ad7255a18 100644 --- a/docs/howto/charts_tips_and_tricks.md +++ b/docs/howto/charts_tips_and_tricks.md @@ -347,6 +347,12 @@ Keep the following in mind when you use `SOURCE_DATE_EPOCH`: - When the variable is unset or empty, Helm keeps the default behavior, where archive entries reflect the actual file modification times. +- When you package a chart that contains a `Chart.lock` file, + Helm also stamps that file's `generated:` timestamp with the `SOURCE_DATE_EPOCH` value, + normalized to UTC and whole seconds. + As a result, charts that declare dependencies produce byte-identical archives across builds and machines + when you use the same `SOURCE_DATE_EPOCH`, + because the `Chart.lock` content matches, not just the file modification times. - `helm install`, `helm upgrade`, `helm dependency build`, and `helm dependency update` also honor `SOURCE_DATE_EPOCH`, but only when they re-archive a dependency sourced from a local `file://` repository.