[ENHANCEMENT] CI check: Containerfile/Dockerfile must have a matching container-build matrix entry

[hbelmiro]

Enhancement Type

• CI/CD enhancement

Problem Statement

container-build.yml triggers on **/Containerfile and **/Dockerfile path changes, but only builds
contexts explicitly listed in strategy.matrix.include. A contributor can add a Containerfile to
a component or pipeline directory and CI will never build it -- syntax errors, missing files, and broken
RUN steps go undetected.

This applies to all component/pipeline locations, including subcategories:

• components/<category>/<component_name>/Containerfile
• components/<category>/<subcategory>/<component_name>/Containerfile
• pipelines/<category>/<pipeline_name>/Containerfile
• pipelines/<category>/<subcategory>/<pipeline_name>/Containerfile

Proposed Solution

A Python script under .github/scripts/check_container_build_matrix/ that:

1. Discovers every Containerfile/Dockerfile recursively under components/, pipelines/,
   and docs/examples/.
2. Parses .github/workflows/container-build.yml and extracts context values from
   jobs.build.strategy.matrix.include.
3. Fails if any discovered file's parent directory has no matching matrix context.

A new workflow (e.g., .github/workflows/container-build-matrix-check.yml) triggers on PRs touching
**/Containerfile, **/Dockerfile, or .github/workflows/container-build.yml and runs the script.

This follows the existing pattern of check_imports and validate_base_images.

Validation sketch

SEARCH_ROOTS = ["components", "pipelines", "docs/examples"]

def check():
    container_files = []
    for root in SEARCH_ROOTS:
        container_files += Path(root).rglob("Containerfile")
        container_files += Path(root).rglob("Dockerfile")

    matrix_contexts = parse_matrix_contexts(".github/workflows/container-build.yml")

    unmatched = [cf for cf in container_files if str(cf.parent) not in matrix_contexts]

    if unmatched:
        for f in unmatched:
            print(f"ERROR: {f} has no matching matrix entry in container-build.yml")
        sys.exit(1)

Additional considerations

• Support an exclusion mechanism (YAML config or CLI flag) for files not intended to be built by CI.
• Error messages should tell the contributor exactly what to add to container-build.yml, referencing
  the Adding a Custom Base Image docs.
• Unit tests following .github/scripts/ patterns.

Use Cases

1. Contributor adds a Containerfile without a matrix entry -- CI fails with a clear message.
2. Contributor adds a Containerfile inside a subcategory without a matrix entry -- CI fails.
3. Contributor removes a matrix entry but leaves the Containerfile -- CI fails.
4. Contributor adds both the Containerfile and the matrix entry -- CI passes.

Alternatives Considered

• Code review only: fragile, already proven insufficient.
• Dynamic matrix generation: higher complexity; can be pursued separately.
• Inline shell step: less testable, inconsistent with repo patterns.

Willing to Contribute

• Yes, I can implement this enhancement
• Yes, I can help with testing
• Yes, I can help with documentation

---

Interested in this enhancement? Give it a 👍.

[prachimaskar]

Hi @hbelmiro, I'd like to work on this issue if it's still open!

Here's my plan:

• A Python script under .github/scripts/check_container_build_matrix/ following the existing check_imports / validate_base_images patterns
• Recursively discovers all Containerfile/Dockerfile paths under components/, pipelines/, and docs/examples/
• Validates each one has a matching context in the container-build matrix, failing with a clear message that tells the contributor exactly what to add
• A .container-build-ignore file at the repo root for the exclusion mechanism (for files not intended to be built by CI)
• A new workflow .github/workflows/container-build-matrix-check.yml triggering on PRs that touch **/Containerfile, **/Dockerfile, or container-build.yml
• Unit tests following .github/scripts/ conventions

Would you be happy for me to go ahead and open a PR? Happy to adjust the approach based on any feedback!