Skip to main content

Documentation Index

Fetch the complete documentation index at: https://tally.wharflab.com/llms.txt

Use this file to discover all available pages before exploring further.

OCI base digest labels must be backed by a digest-pinned base image.
PropertyValue
SeverityWarning
CategoryCorrectness
DefaultEnabled
Auto-fixSuggestion, for standalone LABEL instructions and grouped LABEL pairs

​
Description

org.opencontainers.image.base.digest is the digest of the image this image is based on. It is not the digest of the image produced by the current Dockerfile. For a Dockerfile-owned label to be trustworthy, the exported image’s stage chain must include a digest-pinned external base image, such as FROM alpine:3.20@sha256:..., and the label value must match that digest. If the exported image is built from FROM alpine:3.20, FROM scratch, or a stage chain whose external base is not pinned by digest, a checked-in org.opencontainers.image.base.digest label can only drift from the actual base image selected during the build. This rule checks labels that affect the exported image. Labels in throwaway builder stages are ignored unless the final image inherits from that stage.

​
Examples

​
Bad: Unpinned base

FROM alpine:3.20

LABEL org.opencontainers.image.base.digest="sha256:1111111111111111111111111111111111111111111111111111111111111111"
The FROM line is tag-based, so the Dockerfile does not prove the base image digest.

​
Bad: Mismatched digest

FROM alpine:3.20@sha256:1111111111111111111111111111111111111111111111111111111111111111

LABEL org.opencontainers.image.base.digest="sha256:2222222222222222222222222222222222222222222222222222222222222222"
The FROM line is digest-pinned, but the label disagrees with it.

​
Good: Matching digest

FROM alpine:3.20@sha256:1111111111111111111111111111111111111111111111111111111111111111

LABEL org.opencontainers.image.base.digest="sha256:1111111111111111111111111111111111111111111111111111111111111111"

​
Good: Omitted without pinned base

FROM alpine:3.20

LABEL org.opencontainers.image.title="app"
When the base image is not digest-pinned, omit org.opencontainers.image.base.digest.

​
Multi-stage Builds

When the final image inherits from another Dockerfile stage, Tally follows that FROM <stage> chain to the first external base image: 
FROM alpine:3.20@sha256:1111111111111111111111111111111111111111111111111111111111111111 AS base

FROM base
LABEL org.opencontainers.image.base.digest="sha256:1111111111111111111111111111111111111111111111111111111111111111"
This is valid because the exported image still traces back to a digest-pinned external base. A label in a builder-only stage is ignored when the exported image does not inherit from that stage.

​
Fixes

For LABEL org.opencontainers.image.base.digest=..., Tally offers two suggestion-level fixes when the source pair can be mapped precisely:
  • comment out the instruction, preserving the original text for review
  • delete the instruction or pair
When org.opencontainers.image.base.digest appears inside a grouped LABEL, Tally removes only that key/value pair and preserves the unrelated labels. The comment-out fix inserts a commented standalone LABEL before the grouped instruction, then removes the active pair from the group. Fixes are scoped to the exported image’s stage chain. If a final stage shadows an inherited stale base digest label, the suggested fix also removes the inherited copy so applying the fix once does not reveal the same issue again. Builder-only stages outside the exported chain are still ignored.