LABEL Build Field

The LABEL build field records information specific to the particular build that produced an image — a build date, a build number, a commit hash — directly within its metadata, providing detailed traceability about exactly when and how that specific image was produced.

Common Build-Related Labels

Build-related labels typically capture details that are useful for tracing an image back to the exact circumstances of its creation.

ARG BUILD_DATE
ARG BUILD_NUMBER
ARG GIT_COMMIT
LABEL build.date=$BUILD_DATE
LABEL build.number=$BUILD_NUMBER
LABEL build.commit=$GIT_COMMIT

docker build \
  --build-arg BUILD_DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ) \
  --build-arg BUILD_NUMBER=$CI_BUILD_NUMBER \
  --build-arg GIT_COMMIT=$(git rev-parse HEAD) \
  -t myapp:1.0 .

Why Build Date Matters Despite Image Immutability

Even though an image's content is immutable, recording when it was actually built is useful for understanding how current a deployed image is relative to when it was produced, particularly when investigating an issue that might be related to the age of the running code.

docker inspect myapp:1.0 --format '{{index .Config.Labels "build.date"}}'

Linking Back to CI Pipeline Runs

A build number label can be used to look up the exact CI pipeline run that produced a given image, providing access to detailed build logs if something about that specific build needs further investigation.

docker inspect myapp:1.0 --format '{{index .Config.Labels "build.number"}}'

Why Build Field Labels Matter

Detailed build metadata recorded as labels turns an otherwise opaque image into something whose exact origin — when it was built, by which pipeline run, from which commit — can be reconstructed directly from the artifact itself, which is valuable for debugging, auditing, and understanding the provenance of anything currently deployed.