A Docker image builds on your laptop but not in CI: compare what the clean checkout lacks

What a clean checkout takes away

On your laptop the build runs in a folder that has been accumulating things for months: generated files, untracked configuration, a warm layer cache and a logged-in registry. A CI build starts from a fresh clone, an empty cache and only the secrets the pipeline passes. Anything the Dockerfile silently relied on, and that was never committed, is missing. The build failure is the first time anyone sees the dependency.

The build context and the ignore file

Docker sends the builder a build context, which is the set of files the build can reach. If an ignore file is present in the root of that context, matching files are removed before the builder sees them, and COPY cannot use them. A different ignore file can sit next to a particular Dockerfile and takes precedence over the one at the root. Two things go wrong in CI. The context may be rooted in a different folder from the one you use locally, so a COPY path that worked there does not exist here. And an ignore rule written for convenience, such as excluding a whole folder, may remove a file the build needs but that your laptop never needed to copy because it was already present.

Also compare file names exactly. A name that differs only by letter case between the Dockerfile and the repository can be found on some machines and not on others, so check the spelling character by character.

• Where is the context rooted in CI and locally?
• Which ignore rules apply, and does any match a file the build copies?
• Does every copied file exist in a fresh clone, spelled exactly?

Build arguments, secrets and cached layers

A private package token or similar value must reach the build somehow. Docker documents that build arguments and environment variables are inappropriate for secrets because they persist in the final image, and recommends secret mounts, which make a secret available only while one instruction runs. A build that works only because a token was passed as an argument on a laptop may leak that token into the image, and one that never receives the token in CI fails at the first private download.

Cached layers can also hide a defect. Docker reuses layers whose inputs have not changed and rebuilds every layer after a changed one, so a step that no longer works may still look fine on a machine whose cache contains an old result. A CI runner usually starts without that cache, which exposes the problem.

A read-only comparison

Clone the repository into an empty folder and list its top-level files next to the folder you build from. List the files the Dockerfile copies and check that each exists in the clone. Read the ignore file for rules that match them. Note where the CI step sets its context and how it passes any token. Do not edit anything and do not push a test image over an existing tag. If the failure is a processor-architecture mismatch rather than a build error, the architecture guide covers that separately.

How the paid outcome is accepted

The fixed job covers one image from one Dockerfile. It is accepted when the image builds from a fresh checkout on the CI runner with no layer cache for each platform agreed in advance; when a container started from it passes the agreed health check and stays up for the agreed time; and when the build arguments and image history we inspect show no secret value, none of the credential files you name is copied in, and no existing tag was moved. It starts at £245, untested, and is paid after you sign off. Making the image smaller or faster to rebuild is a separate job.