Q: What is the purpose of a Dockerfile `.dockerignore` file?
In a pipeline, .dockerignore in CI/CD controls which files from the checked-out workspace are sent to the builder and made available to COPY. Its purpose is to keep the build context small, deterministic and free of secrets.
Want to master this scenario in a live sandbox? KodeKloud's Enterprise GitOps with ArgoCD & Kubernetes Rollouts covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: In a pipeline, <strong><code>.dockerignore</code> in CI/CD</strong> controls which files from the checked-out workspace are sent to the builder and made available to <code>COPY</code>. Its purpose is to keep the build context small, deterministic and free of secrets. CI workspaces are messier than laptops: they contain <code>.git</code>, test reports, coverage output, downloaded artifacts and sometimes credential files written by earlier steps. Interviewers ask this to see whether you connect an old Dockerfile feature to cache hit rate, build time and supply-chain safety.
Why CI Workspaces Need Filtering
The pipeline's workspace is the build context, so everything earlier steps wrote is a candidate for the image.
- Noise from earlier steps: test reports,
coverage/,.pytest_cache, built binaries and downloaded caches appear before the Docker step runs. - Credential files: steps that write
.npmrc,~/.awsstyle files or kubeconfigs into the workspace can leak into a layer throughCOPY . .. - Cache invalidation: a changing file, such as a timestamped report, invalidates the
COPY . .layer and every layer after it on each run. - Upload cost: remote builders and BuildKit services receive the context over the network, so size directly adds to job time.
Configure .dockerignore and the Build Step
Keep the ignore file in the repo and build with BuildKit and a registry cache.
# .dockerignore
.git
.github
.env*
coverage/
test-results/
*.log
node_modules
dist
# .github/workflows/build.yml (excerpt)
- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
with:
context: .
push: true
tags: registry.example.com/team/my-app:${{ github.sha }}
cache-from: type=registry,ref=registry.example.com/team/my-app:buildcache
cache-to: type=registry,ref=registry.example.com/team/my-app:buildcache,mode=max
- Ignore pipeline artifacts: list report, cache and CI directories explicitly.
- Copy dependency files first: order the Dockerfile so manifests are copied and installed before sources, then ignore rules protect that cache.
- Same behaviour everywhere: BuildKit and Buildx honour the file, so local and CI builds match.
- Registry cache:
cache-fromandcache-topersist layers across stateless runners.
Verify Context Size and Image Contents in the Pipeline
Add cheap checks so a regression in the ignore file is caught in review.
docker build --progress=plain -t my-app:ci . 2>&1 | grep -i "transferring context"
# Fail the job if sensitive files are present
docker run --rm --entrypoint sh my-app:ci -c \
'find /app -name ".env*" -o -name "*.pem" | grep . && exit 1 || exit 0'
trivy image --scanners secret --exit-code 1 my-app:ci
- Read the context size:
docker build --progress=plain .logs the "transferring context" size; compare it with the previous run. - List the image filesystem: run
ls -laon the app directory of the built image and fail the job if forbidden names appear. - Scan for secrets: Trivy can scan an image for secrets with
--scanners secret. - Review layers:
docker history --no-truncshows the instructions that created each layer.
Failure Modes in Pipelines
Over-ignoring breaks builds; under-ignoring breaks caching and security.
- Build passes locally, fails in CI with "not found": a generated file such as
dist/is ignored but the Dockerfile expects it; build inside a stage instead of copying artifacts. - Cache never hits: check for volatile files in context, for example a generated
version.txtor reports; ignore them or copy them in a late layer. - Wrong ignore file: with a custom
-fDockerfile, a<name>.dockerignorebeside it takes precedence under BuildKit. - Git context builds: when the context is a remote Git reference, only committed files are present, so behaviour differs from a workspace build.
Make It Part of the Delivery Standard
Treat the ignore file like code that gets reviewed and tested.
- Template per language: keep a baseline .dockerignore in your project template so new services start safe.
- Review rule: any new top-level directory must be reviewed against .dockerignore in the same pull request.
- Policy checks: a CI lint step can fail when the file is missing from a repository that has a Dockerfile.
- Multi-stage builds: pair with a lean final stage so build tools and sources never ship.
- .dockerignore filters the CI workspace before it becomes the Docker build context, keeping reports, .git and credential files out of COPY.
- I verify it from the transferring-context size, a filesystem check on the built image and a Trivy secret scan.
- I standardise a baseline file per language, combine it with registry layer caching and BuildKit secret mounts, and review changes alongside the Dockerfile.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Letting COPY . . run after earlier steps wrote reports or credentials into the workspace They become part of the image and constantly invalidate the layer cache.
- Ignoring dist/ while the Dockerfile copies it The build fails only in CI where the artifact path is expected; build artifacts in a stage instead.
- Deleting a secret with a later RUN rm The earlier layer still contains it and can be extracted; keep it out of the context entirely.
- Having no .dockerignore in repositories with a Dockerfile Every CI run uploads .git and workspace noise, slowing builds and risking leaks.