Skip to content

require-labels

OCI image labels: using LABEL org.opencontainers.image.* to link a Docker image back to its source repo, revision, and license.

On this page

Six months from now, someone will be staring at an image in a registry asking: which repo builds this, which commit is it, who owns it? Without labels the answer is archaeology. This rule suggests adding LABEL metadata — ideally the standard org.opencontainers.image.* keys — so the image itself carries the answer.

What the rule catches

Dockerfile — anonymous image
FROM node:22-slim
WORKDIR /app
COPY . .
CMD ["node", "server.js"]

Scanning this file reports:

ℹ INFO [docker-doctor/require-labels]
  No LABEL metadata was found in this Dockerfile. Adding labels helps identify build information, maintainers, and descriptions.

Why it matters

Labels are machine-readable provenance. Registries (GitHub Container Registry among them) read org.opencontainers.image.source to link an image to its repository; vulnerability scanners and SBOM tools pick up version and license labels; incident responders use revision to go from a running container to the exact commit. It's a few bytes of metadata that makes every downstream tool smarter, and CI can inject the dynamic values so they're never stale.

How to fix it

Use LABEL instructions (e.g. LABEL org.opencontainers.image.authors="...") to document ownership, license, version, and build info.

Dockerfile — image carries its provenance
FROM node:22-slim
LABEL org.opencontainers.image.source="https://github.com/acme/api" \
      org.opencontainers.image.description="Acme API server" \
      org.opencontainers.image.licenses="MIT"
WORKDIR /app
COPY . .
CMD ["node", "server.js"]

Keep static labels (source, license, description) in the Dockerfile and inject per-build values at build time: docker build --label org.opencontainers.image.revision=$GIT_SHA. If you build with docker/metadata-action in GitHub Actions, the standard OCI labels are generated for you. The full key list lives in the OCI image spec annotations.

Rule details

  • Rule key — docker-doctor/require-labels
  • Category — Best Practices
  • Default severity — info
  • Applies to — Dockerfiles

Explain this rule from the CLI:

npx @docker-doctor/cli@latest rules explain docker-doctor/require-labels

Change its severity — or turn it off — in your config file:

// docker-doctor.config.ts
export default {
  rules: {
    "docker-doctor/require-labels": "off",
  },
};

Severity affects the health score: error findings cost more points than warning, and info costs the least.