The Docker LABEL instruction attaches key-value metadata to an image, and used well it turns opaque images into auditable, traceable supply-chain artifacts. A label costs nothing at runtime, adds no layer weight worth mentioning, and answers questions your future self and your security team will absolutely ask: where did this image come from, what commit built it, and who owns it.
Most Dockerfiles skip labels entirely, which is a missed opportunity. The images that are easiest to secure are the ones you can identify, and labels are how you identify them.
The basics
LABEL takes one or more key-value pairs and stores them in the image manifest. You can inspect them later without running the container:
LABEL org.opencontainers.image.source="https://github.com/acme/api"
LABEL org.opencontainers.image.revision="a1b2c3d"
LABEL org.opencontainers.image.version="1.4.2"
Read them back with:
docker inspect --format '{{json .Config.Labels}}' acme/api:1.4.2
Prefer a single LABEL with multiple pairs, or accept that each instruction historically added a layer. On modern builds label instructions are cheap, but grouping them keeps the Dockerfile readable:
LABEL org.opencontainers.image.source="https://github.com/acme/api" \
org.opencontainers.image.revision="a1b2c3d" \
org.opencontainers.image.version="1.4.2" \
org.opencontainers.image.vendor="Acme Inc"
Use the OCI standard keys
Do not invent your own key names when a standard exists. The Open Container Initiative defines a set of org.opencontainers.image.* annotation keys that tooling across the ecosystem already understands. The ones worth setting on every image:
org.opencontainers.image.source— the URL of the source repository.org.opencontainers.image.revision— the exact commit the image was built from.org.opencontainers.image.version— the semantic version or tag.org.opencontainers.image.created— the build timestamp, in RFC 3339.org.opencontainers.image.vendor— the organization that produced the image.org.opencontainers.image.licenses— the SPDX license expression.
These are the same keys docker buildx will populate for you from build context, and registries and scanners read them to link an image back to its origin. Sticking to the standard means your metadata is portable rather than locked to one tool.
Populate labels at build time, not by hand
Hand-typed labels rot immediately. Wire them into the build so every image carries accurate provenance automatically. Pass build arguments and reference them in the label:
ARG GIT_COMMIT
ARG BUILD_DATE
ARG VERSION
LABEL org.opencontainers.image.revision="${GIT_COMMIT}" \
org.opencontainers.image.created="${BUILD_DATE}" \
org.opencontainers.image.version="${VERSION}"
Then in the pipeline:
docker build \
--build-arg GIT_COMMIT="$(git rev-parse --short HEAD)" \
--build-arg BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
--build-arg VERSION="${CI_TAG}" \
-t acme/api:"${CI_TAG}" .
Now the commit that produced any running container is a docker inspect away, which is the difference between a five-minute incident investigation and a five-hour one.
Why labels matter for security
Labels are metadata, not a control, but they are what makes controls possible.
Traceability during incident response. When a scanner reports a vulnerable image running in your cluster, the source and revision labels tell you exactly which repo and commit to patch. Without them you are grepping build logs and guessing.
Provenance and policy. Admission controllers and policy engines can require that images carry specific labels before they are allowed to run, for example rejecting any image without a known vendor or source. That is a cheap way to keep unlabeled, unknown images out of production.
SBOM and scan correlation. When you generate a software bill of materials or run an image scan, the labels let you tie the findings back to a team and a code repository. Correlating image findings with the source that built them is exactly the kind of linkage our container scanning in SCA relies on, and consistent labels make that automatic.
What not to put in a label
Labels are stored in plain text in the image manifest and are readable by anyone who can pull the image. Never put secrets, API keys, or internal tokens in a label. It is the same mistake as baking a secret into an environment variable in the Dockerfile, and image scanners will (rightly) flag it. Keep labels to non-sensitive metadata and inject real secrets at runtime through your orchestrator's secret store.
Also avoid labels that go stale silently, like a hardcoded maintainer email for someone who left. Prefer a team identifier or a link to an ownership registry that outlives individuals. The deprecated MAINTAINER instruction should be replaced with an org.opencontainers.image.authors label.
FAQ
Do LABEL instructions increase image size?
Negligibly. Labels are small metadata stored in the manifest, not filesystem layers with real content. Grouping them into a single LABEL instruction is about readability and layer count, not meaningful size.
What is the difference between LABEL and ENV?
LABEL attaches build-time metadata to the image that you inspect from outside; it is not visible to the running process. ENV sets environment variables that the container's processes read at runtime. Use labels for provenance and documentation, environment variables for configuration.
Should I use the org.opencontainers.image keys or custom ones?
Use the OCI standard keys for anything they cover, because scanners, registries, and build tools already understand them. Reserve custom, reverse-DNS-namespaced keys (like com.acme.team) for organization-specific metadata the standard does not include.
Can labels enforce security policy?
Not on their own, but policy engines and admission controllers can require or inspect labels to make decisions, such as blocking images that lack a source or vendor label. Labels supply the metadata; the policy layer enforces the rule.