Review Docker build targets by dependency rather than stage order

Bottom line: Check what the selected target depends on before treating an earlier stage as completed work. Keep the intended build graph and required checks explicit instead of using the physical order of a Dockerfile as an execution record.

Source fact: documented behavior

The Multi-stage builds documentation is the primary reference.

Docker documents --target as selecting a named stage at which to stop the build. The legacy builder processes stages leading to the selected target even when they are unrelated, while BuildKit builds only the stages on which that target depends. In the guide’s base, stage1 and stage2 example, a BuildKit build targeting stage2 processes base and stage2 and skips independent stage1.

What the source does not establish

This is a target-dependency review, not proof that an application’s tests passed or that an exported artifact is acceptable. It does not recommend using the legacy builder. Confirm the actual builder and required workflow rather than changing implementations to obtain a preferred example trace.

Applicability questions

• Which named stage is the selected target?
• Which earlier stages are actual dependencies of that target?
• Does any required preparation or test exist only in an unrelated stage?
• Which evidence will show the required workflow actually ran?

DSE recommendation: connect required work to the build plan

DSE recommends drawing a small stage graph for the Dockerfile under review. Name the selected target and trace the definitions and artifact transfers that connect it to other stages. Have the build owner distinguish dependencies from unrelated alternatives such as diagnostic or development targets.

List required preparation and tests beside the graph. Decide whether each belongs in the target’s dependencies or in a separately invoked pipeline task. Keep that decision explicit. Do not call an unused stage a completed quality gate simply because its instructions appear before the production target.

Review the actual build invocation with the managed pipeline definition. Retain the target selection and builder identity used by the job that produces the deliverable. Keep local troubleshooting commands separate when they choose a different target. Treat a successful build exit and evidence that the required test task ran as different acceptance observations.

If a missing required step is found, correct the managed workflow through review rather than adding a superficial dependency solely to make a trace longer. Ask the project owner to accept the resulting responsibility for test execution and failure handling. Keep platform selection, final-stage export contents and runtime-dependency checks within their existing separate procedures.

Verification and evidence

Proposed verification, not performed: use a disposable Dockerfile patterned on the documented base-and-two-child-stage example, with harmless distinct markers. Predict which markers the selected target requires under the actual approved builder, then collect the build trace.

In a separate revised fixture, make one previously independent stage an intentional dependency and predict the changed graph before rebuilding. Do not infer test execution solely from marker presence inside an artifact. Retain the Dockerfile revision, invocation, builder identity, dependency graph and actual trace. Reconcile the real pipeline’s required checks independently before accepting its deliverable.

Official references

• Multi-stage builds — Docker Docs.

Source review completed October 29, 2026. Recheck the official documentation and deployment-specific applicability before a production change.