Check generated names and combinations in a Bake matrix

Bottom line: Review the generated target set before running a matrix build. Require a unique name for each intended variant and keep its arguments, tags and output destination tied to the same combination.

Source fact: documented behavior

The Matrix targets documentation is the primary reference.

Bake expands the values of matrix parameters into separate targets for every possible combination. Every generated target requires a unique name, supplied through the name attribute. The documented multiple-axis example combines two target values with two version values to produce four generated names. For file exports, the guide directs each variant to a separate output directory to avoid overwriting another variant’s files.

What the source does not establish

This article reviews target expansion, names and output separation. It does not size build concurrency, establish application compatibility or prescribe the documentation’s sample versions. Keep parent inheritance and variable validation separate, and use harmless variant labels for an initial exercise.

Applicability questions

• Which axes and values define the intended variant population?
• Does the naming expression distinguish every combination?
• Which argument and tag should each generated target receive?
• Are file-export destinations distinct for variants that must remain separate?

DSE recommendation: review the expansion as a complete inventory

DSE recommends writing the expected variant inventory before editing the matrix. Use one row per intended combination, with generated name, relevant argument values, tag and output destination. Have the release owner identify missing or intentionally excluded combinations rather than assuming the matrix expresses the required product set.

Review the name expression against every row. Include values that may normalize to a similar name, and resolve a collision before running builds. Keep a readable display label separate from an identifier that must remain unique. Do not silently remove an axis from the naming expression merely to shorten the generated target names.

Inspect the resolved Bake model through the documented print workflow. Compare the complete target list and selected group with the written inventory, then inspect each target’s relevant values. Retain a discrepancy as a configuration finding instead of accepting a successful parse as proof that the intended variants exist.

For filesystem outputs, assign a dedicated disposable destination to each test variant. Review image tags with the same discipline when separate results must remain identifiable. Keep concurrency policy and release execution under their established controls. Accept the generated configuration first, then authorize only the bounded harmless builds needed to observe its output behavior.

Verification and evidence

Proposed verification, not performed: prepare a small two-axis fixture using harmless labels and a nonsecret build argument. Write the four intended combinations and unique target names before running docker buildx bake --print through the approved test workflow. Compare the actual model with that inventory.

If file outputs are in scope, use a harmless marker build and separate empty destinations. Compare each observed marker with its target and input values. Include a name-collision review as a separate configuration case without relying on an unverified error message. Retain the definition, resolved target set, invocation and output inventory. Report the tested expansion and mapping, without claiming every possible value or application variant was validated.

Official references

• Matrix targets — Docker Docs.

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