Validate ESP-Matter on every branch, on the base that run produced

[hacker-cb]

A pull request touching only images/esp-matter/** matched the workflow's paths:
filter, so esp-idf-build ran on its unchanged context and reported success. The
check was not merely absent — it was misleading, and CLAUDE.md carried a
paragraph warning readers not to trust it.

The cause was one line: needs: esp-idf-manifest on a job whose dependency only
runs on master. A needs on a skipped job skips the dependent too.

ESP-Matter now builds on every branch

esp-matter-build depends on esp-idf-build instead, and takes the digest for its
own platform from that job's artifact. Both branches behave identically — no status
expressions, no registry probing, no fallbacks.

That required esp-idf-build to push by digest on every run, not just master.
Nothing published that way is reachable by name: only the manifest jobs create
tags, and they stay master-only. So a pull request moves no tag and leaves untagged
blobs behind — they accumulate and want an occasional cleanup, which is the
price of this.

What it buys is that a branch bumping ESP-IDF and Matter's base_tag together —
exactly what the next PR does — is checked as the pair it will become. The first
version of this change resolved the base from the registry instead, and review
showed that hollowed out the very case the validation exists for: on such a PR the
new base is published under no tag, so the build fell back to :latest (the old
image) and reported green, with the real pairing first meeting on master after the
esp-idf tags had already been republished.

Documentation-only changes trigger nothing

!images/**/*.md is excluded from both workflows' paths:. The docs-only merge
that started this series set off a full rebuild including a 5.5-hour ESP-Matter leg
and republished every tag for images whose contents had not changed.

Two holes closed along the way

Fork pull requests were running on this org's paid pools, and had been since
before this series. On a PR from a fork, github.repository_owner is the base
repository — jethome-iot — so the owner check every build job carries was already
true, and a fork-controlled Dockerfile executed on our machines. Every build job
now also requires github.event.pull_request.head.repo.full_name == github.repository.

Dependabot cannot push packages: GitHub hands its runs a read-only
GITHUB_TOKEN whatever permissions: asks for. Since Dependabot was enabled two
PRs ago and its updates edit workflow files — which are in the paths filter — the
first automated bump would have failed on the digest push. Those runs skip the push
and the upload, and esp-matter-build sits them out; the bump is still exercised by
esp-idf-build compiling the image.

Not done, deliberately

The workflows are not split into one file per image. Splitting would break the
digest handoff, which is scoped to a single run — the alternatives being a
workflow_run trigger fetching another run's artifact through the API, or a return
to building on a mutable tag. Both cost more than the duplicated esp-idf-build
leg that a matter-only PR runs, which is ~1.5 minutes.

esp-matter-build also runs for PRs that only touch shared files (a PlatformIO
version bump reaches it through images/versions.json). Gating on the changed
paths was considered and declined: ~$0.6 on those runs, against a config that stays
simple.

Reviewed by

codex-review (xhigh), three rounds — the last one clean. It caught the fork-PR
hole, the coordinated-bump failure at FROM, a manifest job reported skipped
rather than failed after a build failure, and then, on the reworked version, that
the login had stayed master-only while the push became unconditional, plus the
Dependabot token.

The code-review workflow (high) — ten defects, all confirmed. Beyond those above:
!cancelled() drops the implicit success() over every needs, so a failed
prepare surfaced as Unexpected end of JSON input from an empty matrix instead
of the message check-versions.sh had already written; and the first draft's
docker manifest inspect probe swallowed every registry error as "tag not
published", silently substituting a different base.

[Copilot]

Pull request overview

Updates the repository’s Docker image CI workflows and documentation so ESP-Matter is reliably build-validated on PRs/dev using the ESP-IDF image produced in the same workflow run, while reducing unnecessary rebuilds and tightening fork/Dependabot behavior.

Changes:

• Make esp-matter-build depend on esp-idf-build and consume per-platform base-image digests from build artifacts (instead of the master-only manifest job).
• Exclude images/**/*.md from workflow paths: filters to prevent documentation-only changes from triggering image rebuilds.
• Add a head-repo check to prevent fork PRs from running on org runner pools; special-case Dependabot to avoid failing on GHCR pushes.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
README.md	Updates repo-level docs to reflect new validation behavior and doc-only trigger exclusion.
CLAUDE.md	Updates the repo’s CI/Docker image guidance to match the new digest handoff and validation model.
.github/workflows/platformio.yml	Excludes images/**/*.md from triggers and adds fork PR runner-pool protections.
.github/workflows/esp-idf.yml	Implements digest push/artifact handoff enabling ESP-Matter validation on PR/dev; adds doc-only trigger exclusion and fork/Dependabot handling.

---

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

[Copilot]

Pull request overview

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

Suppressed comments (2)

README.md:139

• The README note says every image is validated on “pull requests”, but the workflows intentionally skip PRs from forks via the head-repo check. Without clarifying that, this line can be read as promising validation on all PRs (including forks), which isn’t true.

**Note:** every image is build-validated on pull requests and on `dev`, including
one built `FROM` another image of this repo, and on the base that same run
produced — so a change touching both images is checked as the pair it will become.

.github/workflows/esp-idf.yml:355

• This step assumes the downloaded artifact contains exactly one file and then picks the first filename as the digest. If the artifact ever contains multiple files (or an unexpected filename), this can silently select the wrong digest and build esp-matter on the wrong base. Since the comment asserts “One file”, it’s safer to enforce exactly one file and validate it’s a full 64-hex sha256 digest.

          set -euo pipefail
          # One file, named after the digest it stands for.
          digest=$(find /tmp/base -type f -printf '%f\n' | head -1)
          case "${digest}" in
            [0-9a-f]*) ;;
            *) echo "::error::no usable base digest in the artifact"; exit 1 ;;