#7039·buildah

Add `--sanitize-history`: strip history content but preserve layer structure

Author: chkpntCreated Aug 14, 2026Updated Sep 14, 2026
Labelsstale-issue

Summary / Motivation

--omit-history removes the entire history array. For base images this is destructive in a non-obvious way: the resulting image has layers but no history, which breaks downstream consumers in several ways (see the linked bug issue):

  • Buildah 1.42.x silently force-omit history for any image built FROM such a base, so the history loss propagates down the lineage.
  • Podman 4.9.5 fails the downstream build outright (internal error: history lists N non-empty layers, but we have M layers on disk).
  • Docker 24.0 accepts the base but appends child history without placeholder records for the inherited layers, so layer-aware tools such as dive misattribute history to the wrong layers.

For reproducible builds, the actual goal is usually not "no history" but "no non-deterministic or sensitive content in history" (timestamps, cache references, commands). --omit-history conflates "hide the content" with "remove the structure."

Proposal

Add a --sanitize-history flag (name TBD) to buildah build and buildah commit that keeps one history entry per existing entry but strips the descriptive fields, preserving each entry's empty_layer value so the layer↔history correspondence stays valid.

Equivalent transformation on the image config:

.history |= map({ empty_layer: (.empty_layer // false) })

i.e. drop created, created_by, author, and comment; keep empty_layer exactly as it was (true for metadata-only steps, false/absent for layer-producing steps).

Why this is better than the alternatives

  • --omit-history: removes the structure, so downstream builds hit forceOmitHistory / the consistency error, and the history loss propagates. --sanitize-history keeps the structure, so consumers can append.
  • Docker-style append-without-padding: keeps the build working but misaligns history with layers (the dive problem). --sanitize-history keeps the alignment intact.
  • It still removes the non-deterministic / sensitive content (commands, cache references, timestamps), which is the real reason people reach for --omit-history.
  • It produces a spec-legal image that both Docker/BuildKit and Buildah/Podman handle correctly.

Notes

  • Naming: --sanitize-history or --redact-history; --clear-history is probably too close to --omit-history.
  • The layer count and which steps produced layers remain visible (they already are, via rootfs.diff_ids); only the descriptive text is removed.
  • Today this requires editing the config blob and recomputing the config/manifest digests; a native flag would avoid that.

Related

Bug: #7037

Source: podman-container-tools/buildah