Hand images between jobs by digest, not by tag

[hacker-cb]

The manifest jobs assembled a multi-arch image out of tag names, looked up when
they ran rather than received from the build legs that produced them:

docker buildx imagetools create -t ...:latest -t ...:sha-9e27a4a \
  ghcr.io/.../esp-idf:idf-v5.4.1-linux-amd64 \    # resolved now, not then
  ghcr.io/.../esp-idf:idf-v5.4.1-linux-arm64

Two pushes to master overlapping — a routine shape, since esp-matter runs for
minutes after esp-idf finishes — and run A's manifest publishes what run B
overwrote, under sha-<commit-of-A>. The one tag that is supposed to mean this
exact commit was the one that could lie.

Digest handoff

Build legs push by digest and carry no tag at all:

outputs: type=image,name=…,push-by-digest=true,name-canonical=true,push=${{ github.ref_name == 'master' }}

The digests travel to the manifest job as one empty file per leg, named after the
digest, through an artifact — matrix legs cannot each set a job output, they
overwrite one another. The manifest is then built from @sha256: references, so
nothing in between is a name something else could rebind.

The -linux-<arch> tags disappear from GHCR with this. They existed only as this
handoff and were already documented as "not intended for direct use"; the tag
tables in the three image READMEs drop that row.

esp-matter builds on a pinned base

esp-idf-manifest exports its own digest as a job output, and esp-matter-build
consumes it:

build-args: |
  BASE_IMAGE=ghcr.io/…/jethome-dev-esp-idf@${{ needs.esp-idf-manifest.outputs.digest }}

Before this, an esp-matter build could be sitting on a base that a later run had
already replaced, and the two halves of one multi-arch latest could come from
different bases.

That turns ARG BASE_IMAGE_TAG into a single ARG BASE_IMAGE carrying the whole
reference, because a digest needs @ where a tag needs :. It also stops
hardcoding the owner in FROM, so a fork — or a local build — can point at its own
esp-idf:

./scripts/build.sh esp-idf
docker build --build-arg BASE_IMAGE=jethome-dev-esp-idf:local images/esp-matter

Concurrency

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

Queue on master, cancel on pull requests. Cancelling a master run would leave
images pushed by digest with no manifest pointing at them.

Verification

• ./scripts/lint.sh green — and it caught SC2046 in the first draft of the
  manifest step, where the digest list relied on word splitting; it is an explicit
  array now
• ARG BASE_IMAGE proven both ways locally: the Dockerfile default resolves, and
  --build-arg BASE_IMAGE=jethome-nonexistent-base:proof makes Docker resolve
  metadata for exactly that reference, so the argument does reach FROM
• Publishing itself is master-only, so the digest handoff runs for real on merge —
  the PR checks exercise the build legs with push: false

Reviewed by

codex-review (xhigh) — no findings; it confirms the handoff follows the standard
Buildx multi-platform pattern.

The code-review workflow (high) — ten defects, six confirmed, all applied:

• concurrency did not queue. cancel-in-progress: false is not a queue —
  GitHub cancels a pending run in a group whenever a newer one arrives, whatever
  that flag says. Grouping master pushes by ref would have dropped the middle
  commit of any three landing inside one build window, and its sha-<commit>
  image. The key now carries github.sha on a push, so every commit has its own
  group; pull requests still group by ref and cancel.
• imagetools inspect | jq had no pipefail. jq exits 0 on empty input, so
  a transient GHCR failure would have produced an empty digest, a green manifest
  job, and a failure surfacing much later inside esp-matter-build as invalid reference format, pointing nowhere near the job that broke.
• The manifest jobs globbed whatever digests were present. With
  fail-fast: false, one failed leg leaves a single file — and would publish a
  single-platform image under latest. Each manifest job now asserts one digest
  per platform first.
• Two traps a second matrix version would have sprung — exactly what PR-5 adds.
  The base digest travelled as a scalar output from a matrix job (the overwrite
  hazard the build job's own comment warns about), and artifact names omitted the
  version, so two versions would collide under a version-agnostic download
  pattern. Both fixed, and the fix binds base to tag: a half-done bump now fails on
  a missing artifact instead of publishing idf-v<old> built on v<new>.
• Documentation this branch had falsified: CLAUDE.md still described
  esp-matter as FROM a hardcoded tag, still explained a half-bumped version
  through tags that no longer exist, and still named push: as a top-level key.

[Copilot]

Pull request overview

This PR hardens the Docker image publishing workflows by handing off build outputs between matrix legs and manifest jobs via immutable image digests (artifacts), instead of mutable tag names that can be overwritten by overlapping runs.

Changes:

• Update esp-idf.yml and platformio.yml to push per-platform images by digest (no intermediate tags), upload those digests as artifacts, and assemble multi-arch manifests from @sha256: references.
• Pin esp-matter builds to the exact ESP-IDF base image produced in the same run by passing a full BASE_IMAGE reference (including digest) into FROM.
• Remove documentation of *-linux-<arch> tags from image READMEs and update repo guidance to reflect digest-based handoff and revised build args.

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
.github/workflows/esp-idf.yml	Switch ESP-IDF + ESP-Matter workflows to digest artifact handoff, manifest assembly by digest, and base digest propagation to ESP-Matter.
.github/workflows/platformio.yml	Switch PlatformIO workflow to digest artifact handoff and manifest assembly by digest.
images/esp-matter/Dockerfile	Replace tag-shaped base arg with full BASE_IMAGE reference used directly in FROM.
images/esp-matter/README.md	Document BASE_IMAGE build arg and add local-build-on-local-base example; drop platform-specific tag docs.
images/esp-idf/README.md	Drop platform-specific tag docs now that per-arch tags are no longer published.
images/platformio/README.md	Drop platform-specific tag docs now that per-arch tags are no longer published.
CLAUDE.md	Update repo CI guidance to match digest-based workflow behavior and new base pinning approach.

---

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