Docker Build Checks

Docker build checks analyze a Dockerfile and related build configuration before an image is created. BuildKit reports rules that can reveal unreliable syntax, platform mistakes, ignored files, exposed secrets, and practices that make containers harder to operate.

You can run checks alone with docker build --check or allow them to run during a normal build. This creates a fast feedback step for local development and continuous integration.

Run Docker Build Checks

Pass the build context just as you would for an ordinary image build.

Example:

# Analyze the Dockerfile without producing an image.
docker build --check .

The command evaluates the complete Dockerfile and prints the rule name, explanation, line number, and relevant source. When a check-only invocation finds a violation, it returns a non-zero exit status.

Understand a Check Result

Consider this Dockerfile:

Example:

# syntax=docker/dockerfile:1
FROM alpine:3.23

WORKDIR /app
COPY . .

# Shell form can handle operating-system signals unexpectedly.
CMD echo "Application started" && sleep 3600

A build check can report JSONArgsRecommended for the shell-form command. Use JSON form so the executable receives signals directly.

Corrected example:

# syntax=docker/dockerfile:1
FROM alpine:3.23

WORKDIR /app
COPY . .

# JSON form gives the process predictable signal handling.
CMD ["sh", "-c", "echo 'Application started' && sleep 3600"]

Common Docker Build Check Rules

Fail a Normal Build on Violations

Normal builds report check findings as warnings by default. Add the check parser directive to make violations fail the build.

Example:

# syntax=docker/dockerfile:1
# check=error=true

FROM alpine:3.23

# The build stops when a stable check reports a violation.
CMD ["echo", "Container is ready"]

Tip: Pin the Dockerfile syntax version when error=true is used. Otherwise, a newly introduced check could unexpectedly begin failing an unchanged build.

Configure Checks from the Command Line

Use the BuildKit build argument when CI or a temporary command should control behavior without editing the Dockerfile.

Example:

# Treat every reported stable violation as an error.
docker build --check \
  --build-arg "BUILDKIT_DOCKERFILE_CHECK=error=true" .

Skip a Specific Rule

Fix valid findings whenever possible. If a rule does not fit a documented case, skip only that rule and explain the decision near the directive.

Example:

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

FROM alpine:3.23

# Shell expansion is intentionally required in this small example.
CMD echo "Running on $(uname -m)"

Separate several rule names with commas. Rule names are case-sensitive and use PascalCase.

Combine Skip and Error Settings

Separate directive parameters with a semicolon.

Example:

# syntax=docker/dockerfile:1
# check=skip=JSONArgsRecommended;error=true

FROM alpine:3.23

# All other stable findings fail the build.
CMD echo "Starting service"

Avoid skip=all in shared Dockerfiles because it removes useful protection from future changes.

Enable Experimental Checks Carefully

Experimental checks are disabled by default and may change before becoming stable. Enable them when a project can accept that change rate.

Example:

# Evaluate every currently available experimental check.
docker build --check \
  --build-arg "BUILDKIT_DOCKERFILE_CHECK=experimental=all" .

You can enable selected experimental rule IDs instead of enabling them all. Review results before making experimental checks mandatory in CI.

Check a Specific Build Stage

Multi-stage Dockerfiles can be checked for a selected target.

Example:

# Evaluate the production target without executing its build.
docker build --check --target production .

Without --target, Docker evaluates the entire Dockerfile.

Add Build Checks to CI

Run checks before expensive tests or multi-platform image builds. A simple pipeline step can stop the workflow when validation fails.

Example:

steps:
  - name: Check Dockerfile
    # Stop early when Docker reports a configuration violation.
    run: docker build --check .

  - name: Build image
    run: docker build --tag example/app:test .

Build Check Best Practices

• Run checks locally and in CI so feedback arrives early.
• Pin the Dockerfile syntax version before making warnings fatal.
• Fix findings instead of skipping broad groups of rules.
• Never pass secrets through Dockerfile ARG or ENV instructions.
• Keep dockerignore aligned with files referenced by COPY instructions.
• Review new stable and experimental rules during Docker upgrades.

Conclusion

Docker build checks provide fast static analysis for Dockerfiles and BuildKit configuration. Use docker build --check during development, promote stable checks to CI errors, and document narrow exceptions. This prevents avoidable image-build failures and improves the consistency of container definitions.