Build Contexts, .dockerignore, Remote Contexts, Named Contexts, and Deterministic Build Inputs: Concepts, Architecture, and Mental Model

1. The problem: the Dockerfile is not the whole build input

Chapter 07 made the Dockerfile a source-controlled build contract. That contract still cannot be interpreted without an input boundary. When a Dockerfile says COPY . /app, the builder does not read “the repository” in an abstract sense; it reads the build context presented to it after ignore processing. If that context contains credentials, build outputs, large dependency trees, or unrelated source, those files can affect transfer time, cache keys, and security even when the Dockerfile author did not intend them to matter.

The first question for a reproducible build is therefore not only “which Dockerfile?” but also “which exact source set was the builder allowed to see, from where, at which revision, under which ignore rules?”

2. Mental model: source boundary → filtered snapshot → build dependency

flowchart TD
  A[Local directory / Git / tar / URL / stdin] --> B[Context resolver]
  B --> C[.dockerignore or Dockerfile-specific ignore]
  C --> D[BuildKit context snapshot]
  E[Named contexts] --> F[Independent snapshots]
  D --> G[COPY / ADD / RUN mounts]
  F --> G
  G --> H[Cache keys + build result]
  H --> I[Image ID / digest evidence]
            

The default context is selected by the positional argument of docker build or docker buildx build. Named contexts are additional inputs supplied explicitly with --build-context. BuildKit resolves and snapshots those inputs, then Dockerfile operations consume only the sources referenced by the build graph.

3. Context types are different trust and transport models

4. .dockerignore defines a build boundary, not a Git boundary

Before a local filesystem context is sent to the builder, Docker applies ignore rules from .dockerignore at the root of that context. The syntax resembles .gitignore but should not be treated as identical. Docker uses its own pattern matching and preprocessing rules, including support for ** and negation with !. Review the Docker rule set directly rather than copying repository ignore assumptions blindly.

.git
.env
secrets/
node_modules/
dist/
*.log
!dist/release-manifest.json

Ignoring a path removes it from the build context. That reduces what COPY/ADD can read and can reduce transfer/cache invalidation. It is not a general secret-management system: a secret needed during a build belongs in BuildKit secret/SSH mounts, not in an unignored file.

5. Dockerfile-specific ignore files can intentionally narrow different builds

Docker supports ignore files named after a Dockerfile, such as lint.Dockerfile.dockerignore or docs.Dockerfile.dockerignore. When present next to that Dockerfile, the Dockerfile-specific file takes precedence over the root .dockerignore for that build. This is useful when a repository has distinct build purposes, but it also creates a precedence rule that must be reviewed during diagnosis.

6. A branch name is a selector; a commit/checksum is evidence

A Git context can select a branch, tag, ref, pull-request ref, or subdirectory. Docker's current structured URL-query form is recommended over older fragments when supported. For release-critical inputs, pair the human-readable branch/tag/ref with a checksum (alias commit) so the build fails when the name resolves to an unexpected revision.

docker buildx build \
  'https://github.com/example/project.git?tag=v1.2.3&subdir=docker&checksum=0123456789abcdef' \
  --progress=plain

The checksum above is illustrative, not a real dependency. A real lab must obtain the expected revision from the reviewed upstream source and record it in the evidence packet.

7. Named contexts separate logical inputs

Named contexts let a build receive additional sources without widening the default context. A build can expose docs=./docs or a pinned image/Git source under a stable logical name, and the Dockerfile can consume that context as if it were a stage.

docker buildx build --build-context docs=./docs .

# syntax=docker/dockerfile:1
FROM busybox:1.37.0
WORKDIR /app
COPY . ./app
COPY --from=docs / ./docs

Named contexts improve boundary clarity only when each secondary source is itself identified and reviewed.

8. Builder location changes where remote inputs are fetched

With a remote tarball or remote builder, do not assume the machine running the Docker CLI performs every fetch or has the same filesystem paths as the builder. Treat client path, builder path, remote URL, and named-context source as different locations. This distinction becomes essential in CI and multi-node builder scenarios.

9. Build-input evidence map

10. Small challenge: draw the smallest safe context

A repository contains src/, docs/, .git/, .env, a 500 MB node_modules/, and a generated dist/. The application image needs only src/ and one generated manifest; documentation is processed separately. Decide what belongs in the default context, what should be ignored, and whether docs/ deserves a named context. State the evidence that would prove your decision.

Knowledge check

Official references and version notes

• Build context — authoritative behavior for local directories, Git repositories, tarballs, stdin/empty contexts, .dockerignore, Dockerfile-specific ignore files, Git URL queries/checksums, and named contexts.
• docker buildx build — --build-context, progress, outputs, metadata, and accepted named-context source types.
• Optimize cache usage — why a small context improves transfer and cache behavior and how .dockerignore reduces unnecessary input.
• Dockerfile reference — how COPY, ADD, and RUN --mount consume build inputs.
• Build best practices — source-control, cache, image, and reproducibility guidance.
• Docker Engine 29 release notes — current Engine baseline and fixes.
• Buildx releases — current Buildx feature/compatibility history.
• BuildKit releases — current BuildKit and built-in Dockerfile frontend releases.