Manual workflow arm64-attach.yaml to restore an arm64 entry on an EXISTING cac / cac-fpm tag (php82..86) without rebuilding or altering the amd64 image. Needed because the 2026-11-19 builds (runs 5684/5685) published cac:php82/83 and cac-fpm:php82/83/85 amd64-only after their arm64 legs failed on network steps, overwriting the earlier multi-arch indexes.
How (one leg per run, runs serialised by a concurrency group)
Validate inputs (image in cac|cac-fpm, phpver 82..86, force true|false); inputs only reach the shell through env.
Plan (read only): tag exists, exactly one linux/amd64 entry, no arm64 entry yet (else exit 3, before the 10-20 min build). Remembers the index digest.
Build ONLY linux/arm64 (QEMU, same Dockerfile/build-args as build-push, push by digest, untagged). Not continue-on-error: a failure fails the run and touches nothing.
scripts/verify-image-arch.py: arm64 entry key binaries must be ELF e_machine 0xB7 (AArch64); the existing amd64 entry 0x3E (x86-64). Nothing is executed (docker create + docker cp). Idea from haproxy-manager-base PR #22.
PHP version parity: existing amd64 php -r 'echo PHP_VERSION;' must equal the new arm64's (QEMU), else refuse.
scripts/attach-arm64-index.sh: imagetools create -t <tag> <repo>@<current index> <repo>@<arm64>; the current index is carried over as-is (amd64 manifest AND its attestation, byte-identical descriptors). Refuses if the tag moved since the plan (--expect-index). After the create it re-reads the tag: amd64 manifest digest MUST equal the before value and exactly one arm64 entry MUST exist, otherwise the previous index is re-created and the step fails. force=true replaces an existing arm64 entry (then the amd64 manifest is carried over by digest; its attestation entry is not).
Nothing else changes
No push/pull_request trigger, no tag names as inputs (tag = php<phpver>), never latest, no amd64 build, no effect on build-push.yaml jobs (only the Shell-Checks list/test steps gained the new scripts).
Tested
Shell-Checks exactly as the workflow runs them (shellcheck -S warning on the full list, bash -n, every test): all green; lsphp-abi-gate skip-fails here (no pahole), as known.
New tests: attach-arm64-index.test.sh (stub registry, 40 checks incl. rollback), verify-image-arch.test.sh (stub docker, ELF fixtures: wrong arch, ELF32, big-endian, non-ELF, dir, missing), 10 new static wiring tests in multiarch-workflow.test.py.
Real buildx E2E against a throwaway local registry: amd64-only index with attestation -> attach -> amd64 digest identical, attestation kept, arm64 added; second attach refused (rc 3); --force replaced it; restoring a previous index via imagetools create reproduced the identical index digest.
verify-image-arch.py run against the real cac-fpm:php86 amd64 (0x3E) and arm64 (0xB7) images.
Measured caveat (please read)
The amd64 MANIFEST/config/layers stay identical, but the TAG's index digest necessarily changes (arm64 entry added). On a Docker host with the containerd image store (this dev box, Docker 29.9.3, io.containerd.snapshotter.v1) the image ID of a multi-arch tag IS the index digest, and a docker pull --platform linux/amd64 <tag> after the change reports Downloaded newer image with a new ID (measured with a local registry: index digest 25ffb4.. -> 10b8bd.., same amd64 child). So the nightly pull will see these 5 tags as updated on such hosts. There is no way to add an arm64 entry to a tag without that. Impact is limited to hosts that already pulled the 11-19 amd64-only index (do it before the fleet roll, not after).
Not in this PR
Policy fixes for the normal build (arm64 serialisation, one retry, "would drop arm64" guard, ELF check before publish) follow in a second PR.
## What
Manual workflow `arm64-attach.yaml` to restore an arm64 entry on an EXISTING `cac` / `cac-fpm` tag (php82..86) without rebuilding or altering the amd64 image. Needed because the 2026-11-19 builds (runs 5684/5685) published `cac:php82/83` and `cac-fpm:php82/83/85` amd64-only after their arm64 legs failed on network steps, overwriting the earlier multi-arch indexes.
## How (one leg per run, runs serialised by a `concurrency` group)
1. Validate inputs (`image` in cac|cac-fpm, `phpver` 82..86, `force` true|false); inputs only reach the shell through env.
2. Plan (read only): tag exists, exactly one linux/amd64 entry, no arm64 entry yet (else exit 3, before the 10-20 min build). Remembers the index digest.
3. Build ONLY `linux/arm64` (QEMU, same Dockerfile/build-args as build-push, push by digest, untagged). Not `continue-on-error`: a failure fails the run and touches nothing.
4. `scripts/verify-image-arch.py`: arm64 entry key binaries must be ELF e_machine 0xB7 (AArch64); the existing amd64 entry 0x3E (x86-64). Nothing is executed (docker create + docker cp). Idea from haproxy-manager-base PR #22.
5. PHP version parity: existing amd64 `php -r 'echo PHP_VERSION;'` must equal the new arm64's (QEMU), else refuse.
6. `scripts/attach-arm64-index.sh`: `imagetools create -t <tag> <repo>@<current index> <repo>@<arm64>`; the current index is carried over as-is (amd64 manifest AND its attestation, byte-identical descriptors). Refuses if the tag moved since the plan (`--expect-index`). After the create it re-reads the tag: amd64 manifest digest MUST equal the before value and exactly one arm64 entry MUST exist, otherwise the previous index is re-created and the step fails.
`force=true` replaces an existing arm64 entry (then the amd64 manifest is carried over by digest; its attestation entry is not).
## Nothing else changes
No push/pull_request trigger, no tag names as inputs (tag = `php<phpver>`), never `latest`, no amd64 build, no effect on build-push.yaml jobs (only the Shell-Checks list/test steps gained the new scripts).
## Tested
- Shell-Checks exactly as the workflow runs them (shellcheck -S warning on the full list, bash -n, every test): all green; `lsphp-abi-gate` skip-fails here (no pahole), as known.
- New tests: `attach-arm64-index.test.sh` (stub registry, 40 checks incl. rollback), `verify-image-arch.test.sh` (stub docker, ELF fixtures: wrong arch, ELF32, big-endian, non-ELF, dir, missing), 10 new static wiring tests in `multiarch-workflow.test.py`.
- Real buildx E2E against a throwaway local registry: amd64-only index with attestation -> attach -> amd64 digest identical, attestation kept, arm64 added; second attach refused (rc 3); `--force` replaced it; restoring a previous index via `imagetools create` reproduced the identical index digest.
- `verify-image-arch.py` run against the real `cac-fpm:php86` amd64 (0x3E) and arm64 (0xB7) images.
## Measured caveat (please read)
The amd64 MANIFEST/config/layers stay identical, but the TAG's index digest necessarily changes (arm64 entry added). On a Docker host with the containerd image store (this dev box, Docker 29.9.3, `io.containerd.snapshotter.v1`) the image ID of a multi-arch tag IS the index digest, and a `docker pull --platform linux/amd64 <tag>` after the change reports `Downloaded newer image` with a new ID (measured with a local registry: index digest `25ffb4..` -> `10b8bd..`, same amd64 child). So the nightly pull will see these 5 tags as updated on such hosts. There is no way to add an arm64 entry to a tag without that. Impact is limited to hosts that already pulled the 11-19 amd64-only index (do it before the fleet roll, not after).
## Not in this PR
Policy fixes for the normal build (arm64 serialisation, one retry, "would drop arm64" guard, ELF check before publish) follow in a second PR.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_0185ukXi4YX5FxJGqhi6qab6
New manual workflow arm64-attach.yaml (cac / cac-fpm, one php leg per run, serialised):
builds ONLY arm64 (QEMU, push by digest, same Dockerfile and build-args), checks the ELF
machine type of the arm64 entry (AArch64) and of the existing amd64 entry (x86-64), checks
PHP version parity, then re-creates the tag index from the existing amd64 entries (carried
over by digest) + the new arm64 via scripts/attach-arm64-index.sh. The amd64 manifest digest
is verified identical afterwards (previous index restored if not). Refuses when the tag already
has arm64 unless force=true, and when the tag moved since the plan.
- scripts/attach-arm64-index.sh (+ stub-registry test)
- scripts/verify-image-arch.py (+ test): ELF e_machine check via docker cp, nothing is executed;
idea from haproxy-manager-base PR #22
- multiarch-workflow.test.py: static wiring checks for the new workflow
- Shell-Checks: new scripts and tests added
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0185ukXi4YX5FxJGqhi6qab6
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
What
Manual workflow
arm64-attach.yamlto restore an arm64 entry on an EXISTINGcac/cac-fpmtag (php82..86) without rebuilding or altering the amd64 image. Needed because the 2026-11-19 builds (runs 5684/5685) publishedcac:php82/83andcac-fpm:php82/83/85amd64-only after their arm64 legs failed on network steps, overwriting the earlier multi-arch indexes.How (one leg per run, runs serialised by a
concurrencygroup)imagein cac|cac-fpm,phpver82..86,forcetrue|false); inputs only reach the shell through env.linux/arm64(QEMU, same Dockerfile/build-args as build-push, push by digest, untagged). Notcontinue-on-error: a failure fails the run and touches nothing.scripts/verify-image-arch.py: arm64 entry key binaries must be ELF e_machine 0xB7 (AArch64); the existing amd64 entry 0x3E (x86-64). Nothing is executed (docker create + docker cp). Idea from haproxy-manager-base PR #22.php -r 'echo PHP_VERSION;'must equal the new arm64's (QEMU), else refuse.scripts/attach-arm64-index.sh:imagetools create -t <tag> <repo>@<current index> <repo>@<arm64>; the current index is carried over as-is (amd64 manifest AND its attestation, byte-identical descriptors). Refuses if the tag moved since the plan (--expect-index). After the create it re-reads the tag: amd64 manifest digest MUST equal the before value and exactly one arm64 entry MUST exist, otherwise the previous index is re-created and the step fails.force=truereplaces an existing arm64 entry (then the amd64 manifest is carried over by digest; its attestation entry is not).Nothing else changes
No push/pull_request trigger, no tag names as inputs (tag =
php<phpver>), neverlatest, no amd64 build, no effect on build-push.yaml jobs (only the Shell-Checks list/test steps gained the new scripts).Tested
lsphp-abi-gateskip-fails here (no pahole), as known.attach-arm64-index.test.sh(stub registry, 40 checks incl. rollback),verify-image-arch.test.sh(stub docker, ELF fixtures: wrong arch, ELF32, big-endian, non-ELF, dir, missing), 10 new static wiring tests inmultiarch-workflow.test.py.--forcereplaced it; restoring a previous index viaimagetools createreproduced the identical index digest.verify-image-arch.pyrun against the realcac-fpm:php86amd64 (0x3E) and arm64 (0xB7) images.Measured caveat (please read)
The amd64 MANIFEST/config/layers stay identical, but the TAG's index digest necessarily changes (arm64 entry added). On a Docker host with the containerd image store (this dev box, Docker 29.9.3,
io.containerd.snapshotter.v1) the image ID of a multi-arch tag IS the index digest, and adocker pull --platform linux/amd64 <tag>after the change reportsDownloaded newer imagewith a new ID (measured with a local registry: index digest25ffb4..->10b8bd.., same amd64 child). So the nightly pull will see these 5 tags as updated on such hosts. There is no way to add an arm64 entry to a tag without that. Impact is limited to hosts that already pulled the 11-19 amd64-only index (do it before the fleet roll, not after).Not in this PR
Policy fixes for the normal build (arm64 serialisation, one retry, "would drop arm64" guard, ELF check before publish) follow in a second PR.
🤖 Generated with Claude Code
https://claude.ai/code/session_0185ukXi4YX5FxJGqhi6qab6