Generate the CI matrices from one versions file

[hacker-cb]

Bumping ESP-IDF meant editing four matrix blocks plus two Dockerfile ARG
defaults — and getting it half right did not fail. Old tags live on in GHCR, so a
manifest job with a stale block quietly republishes the previous version's images
under the new latest.

The repository was already carrying one instance of that drift: CI passed
PIO_VERSION=v6.1.18 while the Dockerfile defaulted to 6.1.18, so every CI build
installed platformio==v6.1.18 and only PEP 440 normalisation made it work.

One file

images/versions.json holds what gets built — platforms mapped to runner pools,
the variants published per image, their build args, which one is primary, and for
a derived image the base tag each variant stands on.
scripts/versions-matrix.sh turns that into the build and manifest matrices, a
prepare job emits them, and every other job reads fromJSON. No matrix is
written in a workflow any more.

A bump is now one edit here plus the matching ARG default — and the checker fails
the build if you do only one.

What the checker enforces

Each check stands for a failure that used to be silent:

Check	What it prevents
every image has a Dockerfile, every Dockerfile an image	an image nobody builds; an entry that fails only once CI reaches it
exactly one primary variant	latest decided by whichever manifest job finished last
tags unique and none a prefix of another	the digest-<image>-<tag>-* glob pulling in another variant's platforms
every variant names its versions in its own tag	a bumped args with a forgotten tag publishing a name that contradicts its contents
every variant passes the same arg names as primary	an absent or misspelled arg falling back to the Dockerfile default under the wrong tag
primary's arg values match ARG defaults	local builds and CI building different images from one commit
every runner is a pool in .github/actionlint.yaml	a typo that queues a leg for 24 hours — runs-on is now runtime, so actionlint cannot see it
every base_tag exists among the base image's tags	idf-v<old> published on v<new>
the base ARG default names primary's base tag	./scripts/build.sh standing on a different ESP-IDF than CI

Verification

Every check was verified by breaking it and confirming the report:

• the real PIO_VERSION mismatch — the first run of the checker caught it
• a base tag the base image does not publish
• two primaries
• an ARG BASE_IMAGE default pointing at the wrong version
• a mistyped arg name in a non-primary variant
• a mistyped runner pool
• a bumped version with a forgotten tag
• a variant with "args": {}
• idf-v5.4.1 as a prefix of idf-v5.4.10

Then built platformio with the generated build args: PlatformIO Core, version 6.1.18.

Reviewed by

codex-review (xhigh) — five defects, two of them P1, both biting exactly when a
second variant is added, which is what PR-5 does: arg names were only checked on
the primary variant, and base_arg was declared in the data while the workflow
hardcoded BASE_IMAGE. Also: timeout_minutes was centralised and then ignored,
runner labels lost actionlint's coverage when runs-on became a runtime
expression, and platform_tag used sub, leaving a slash in linux/arm/v7.

The code-review workflow (high) — ten defects, all confirmed. The mechanism ones
are the table above plus: EXPECTED_PLATFORMS: 2 hardcoded in three jobs against a
platform map of arbitrary length, echo "key=$(generator)" swallowing the
generator's exit status, and $b.args | to_entries crashing on a variant with no
args — a legitimate shape for a derived image that only changes its base.

Left for later, deliberately: the manifest tag-assembly block is now duplicated
three times across two workflows. That is what reusable workflows are for, and it
is a mechanical change once this lands.

[Copilot]

Pull request overview

Centralizes Docker image build/manifest configuration into a single images/versions.json file, generates GitHub Actions matrices from it, and adds a consistency checker to prevent CI/build-arg drift across images and workflows.

Changes:

• Introduces images/versions.json as the single source of truth for image variants, platforms→runner pools, build args, and primary variant selection.
• Adds scripts/versions-matrix.sh (matrix generator) and scripts/check-versions.sh (invariant enforcement against Dockerfile ARG defaults and other constraints).
• Refactors esp-idf.yml and platformio.yml workflows to use a prepare job and fromJSON(needs.prepare.outputs.*) matrices; updates docs in README.md/CLAUDE.md.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
scripts/versions-matrix.sh	Generates build/manifest matrices from images/versions.json for workflow fromJSON consumption.
scripts/check-versions.sh	Validates images/versions.json invariants (Dockerfile presence, primary uniqueness, tag rules, runner pools, ARG consistency, base-tag correctness).
README.md	Documents the new “check versions before a bump” workflow and updates repo tree listing.
images/versions.json	Adds the single source-of-truth data for CI builds (platforms, variants, args, primaries, base relationships).
CLAUDE.md	Updates repo conventions to describe the new versions/matrix/checker mechanism and invariants.
.github/workflows/platformio.yml	Switches workflow matrices to generated outputs; adds prepare job and consistency check.
.github/workflows/esp-idf.yml	Switches esp-idf/esp-matter matrices to generated outputs; adds prepare job and consistency check.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Suppressed comments (1)

scripts/versions-matrix.sh:11

• The header comment says the generator fails when a platform has no runner pool, but versions-matrix.sh does not validate runner values (it will happily emit runner: ""). It’s scripts/check-versions.sh that enforces non-empty runners, so the comment is currently misleading.

# Every entry carries `runner`, so a platform without a pool is impossible to
# express here - the generator fails instead of emitting a leg whose `runs-on`
# resolves to the empty string and never starts.