Build Checks

Docker build checks analyze Dockerfiles before spending time on a full build. Use them as a fast lint step in local development and CI.

Run all default checks against the current directory.

1docker build --check .

The same check mode is available through Buildx.

1docker buildx build --check .

Treat warnings as failures in CI so Dockerfile problems do not drift into the main branch.

1docker build --check .
2docker buildx build --check .

Common failures

Build checks are useful because they catch mistakes that are syntactically valid but operationally weak.

  • UndefinedArgInFrom catches a FROM instruction that uses an ARG that was not defined before it.

  • SecretsUsedInArgOrEnv catches secrets passed through build arguments or environment variables.

  • JSONArgsRecommended catches shell-form CMD or ENTRYPOINT instructions where signal handling can be surprising.

  • StageNameCasing and ReservedStageName catch confusing multi-stage build names.

The right response is usually to make the Dockerfile more explicit. For example, prefer JSON-form commands.

1CMD ["python", "app.py"]

Prefer BuildKit secrets over build arguments for credentials.

1RUN --mount=type=secret,id=npm_token \
2    npm config set //registry.npmjs.org/:_authToken="$(cat /run/secrets/npm_token)"

Policy in the Dockerfile

When a repository wants checks to be strict everywhere, put a check directive near the top of the Dockerfile.

1# syntax=docker/dockerfile:1
2# check=error=true
3FROM python:3-slim

Specific checks can be skipped when there is a documented reason.

1# syntax=docker/dockerfile:1
2# check=skip=JSONArgsRecommended

Use skips sparingly. A skipped check should be reviewed like any other policy exception.

CI example

Run checks before the expensive build and push step.

1set -euo pipefail
2
3docker build --check .
4docker buildx build \
5    --cache-from type=registry,ref="${IMAGE}:buildcache" \
6    --cache-to type=registry,ref="${IMAGE}:buildcache",mode=max \
7    -t "${IMAGE}:${GIT_SHA}" \
8    --push .

References