2026-11-19 21:03:27 -08:00
#!/usr/bin/env bash
# Attach an arm64 image to an EXISTING tag without touching its amd64 content.
#
# Why: a build whose arm64 leg failed publishes the tag amd64-only (assemble-multiarch-index.sh).
# Re-running the whole build to get arm64 back would also rebuild amd64 (new digest, new PHP
# layers). This only re-creates the tag's INDEX: the existing amd64 manifest (and its attestation
# manifest) are carried over by digest, the new arm64 (pushed by digest, never tagged) is added.
#
# attach-arm64-index.sh --repo <registry/path> --tag <tag> --arm64 sha256:<digest> \
2026-11-19 21:11:26 -08:00
# [--expect-index sha256:<digest>] [--force] [--follow-tag <tag>] [--builder <buildx builder>]
2026-11-19 21:03:27 -08:00
# attach-arm64-index.sh --repo <registry/path> --tag <tag> --plan-only [--force] (no --arm64 needed)
#
# Rules (all enforced here so the workflow stays thin and these are testable):
# * The tag must exist, be an image index (or a plain amd64 manifest) and contain exactly one
# linux/amd64 entry. Anything else: exit 1, nothing written.
# * If the tag already has a linux/arm64 entry: exit 3, nothing written, unless --force (then the
# old arm64 entry is replaced; the amd64 manifest is still carried over unchanged).
# * --expect-index: the digest of the tag's current index as read by an earlier step. If the tag
# moved since (a build published meanwhile) exit 1: we never overwrite a newer publish with an
# index derived from an older one.
# * The new arm64 digest must inspect as linux/arm64 and differ from the amd64 digest.
# * After the create the tag is re-read: its linux/amd64 manifest digest MUST be identical to the
2026-11-19 21:11:26 -08:00
# one before and an arm64 entry MUST be present. Otherwise exit 1. The previous index is
# re-created ONLY if our create lost the amd64 entry; a tag that now has a different amd64 (a
# concurrent publish) is never rolled back. Residual window: registry has no conditional PUT,
# so a publish landing between the last read and the create is still overwritten: do not run
# this while build-push runs for the same family.
# * --follow-tag T (e.g. latest for php85): if <repo>:T currently has the very same index digest as
# <tag> had BEFORE the attach (i.e. it is an alias of it), it is re-pointed to the new index so
# the alias keeps equalling the tag. If it differs it is left alone (warning). Never created.
2026-11-19 21:03:27 -08:00
# * --plan-only: run every check above, print the plan, create nothing (an already multi-arch
# tag still exits 3, so a pre-check step fails before an expensive build).
#
# Output (stdout, key=value, also appended to $GITHUB_OUTPUT when set):
# before_index= amd64= after_index= platforms=
# Env: IMAGETOOLS overrides the command (default: "docker buildx imagetools"); tests use a stub.
set -euo pipefail
IMAGETOOLS = ${ IMAGETOOLS :- docker buildx imagetools }
2026-11-19 21:11:26 -08:00
repo = "" ; tag = "" ; arm64 = "" ; expect = "" ; force = 0; plan_only = 0; builder = "" ; follow = ""
2026-11-19 21:03:27 -08:00
die() { echo "attach-arm64-index: $1 " >& 2; exit " ${ 2 :- 1 } " ; }
note() { echo "attach-arm64-index: $* " ; }
while [ $# -gt 0 ] ; do
case " $1 " in
--repo) repo = ${ 2 - } ; shift 2 ;;
--tag) tag = ${ 2 - } ; shift 2 ;;
--arm64) arm64 = ${ 2 - } ; shift 2 ;;
--expect-index) expect = ${ 2 - } ; shift 2 ;;
--force) force = 1; shift ;;
--plan-only) plan_only = 1; shift ;;
2026-11-19 21:11:26 -08:00
--follow-tag) follow = ${ 2 - } ; shift 2 ;;
2026-11-19 21:03:27 -08:00
--builder) builder = ${ 2 - } ; shift 2 ;;
*) die "unknown argument: $1 " 2 ;;
esac
done
dre = '^sha256:[0-9a-f]{64}$'
[[ $repo = ~ ^[ a-z0-9][ a-z0-9._:/-] *$ ]] || die "bad --repo ' $repo '" 2
[[ $tag = ~ ^[ A-Za-z0-9_][ A-Za-z0-9_.-]{ 0,127} $ ]] || die "bad --tag ' $tag '" 2
if [ " $plan_only " = 1 ] && [ -z " $arm64 " ] ; then :; else
[[ $arm64 = ~ $dre ]] || die "--arm64 digest missing or malformed (' $arm64 ')" 2
fi
2026-11-19 21:11:26 -08:00
if [ -n " $follow " ] ; then
[[ $follow = ~ ^[ A-Za-z0-9_][ A-Za-z0-9_.-]{ 0,127} $ ]] || die "bad --follow-tag ' $follow '" 2
[ " $follow " != " $tag " ] || die "--follow-tag equals --tag" 2
fi
2026-11-19 21:03:27 -08:00
if [ -n " $expect " ] ; then [[ $expect = ~ $dre ]] || die "bad --expect-index ' $expect '" 2; fi
2026-11-19 21:11:26 -08:00
if [ " $plan_only " != 1 ] && [ -z " $expect " ] ; then die "--expect-index is required (the digest the plan step read)" 2; fi
2026-11-19 21:03:27 -08:00
bflag =() ; [ -n " $builder " ] && bflag =( --builder " $builder " )
# shellcheck disable=SC2086
it() { $IMAGETOOLS " $1 " " ${ bflag [@] } " " ${ @: 2 } " ; }
# tag_digest <ref>: manifest (index) digest of a ref; empty on failure.
tag_digest() {
2026-11-19 21:14:16 -08:00
it inspect " $1 " --format '{{.Manifest.Digest}}' 2>>" ${ ATTACH_STDERR :- /dev/stderr } " | tail -n 1 | tr -d '[:space:]' || true
2026-11-19 21:03:27 -08:00
}
# arch_of <ref>: image config architecture; empty on failure.
arch_of() {
it inspect " $1 " --format '{{json .Image}}' 2>/dev/null \
| python3 -I -c 'import json,sys; print(json.load(sys.stdin).get("architecture",""))' 2>/dev/null || true
}
# parse <raw-json>: prints "kind=index|single", "amd64=<digests, space separated>", "arm64=<digests>".
parse_index() {
python3 -I -c '
import json, sys
try:
d = json.loads(sys.argv[1])
except Exception:
print("kind=bad"); sys.exit(0)
if isinstance(d, dict) and isinstance(d.get("manifests"), list):
a, r = [], []
for m in d["manifests"]:
p = m.get("platform") if isinstance(m, dict) else None
if not isinstance(p, dict) or "vnd.docker.reference.type" in (m.get("annotations") or {}):
continue
if p.get("os") != "linux":
continue
if p.get("architecture") == "amd64":
a.append(m.get("digest", ""))
elif p.get("architecture") == "arm64":
r.append(m.get("digest", ""))
print("kind=index"); print("amd64=" + " ".join(a)); print("arm64=" + " ".join(r))
elif isinstance(d, dict) and isinstance(d.get("config"), dict):
print("kind=single")
else:
print("kind=bad")
' " $1 "
}
# read_tag <ref>: sets g_digest, g_kind, g_amd64, g_arm64 for the tag as currently published.
read_tag() {
local raw out
g_digest = $( tag_digest " $1 " )
[[ $g_digest = ~ $dre ]] || die "cannot read the manifest digest of $1 (does the tag exist?)"
raw = $( it inspect --raw " $1 " 2>/dev/null) || die "cannot read $1 "
out = $( parse_index " $raw " )
g_kind = $( sed -n 's/^kind=//p' <<< " $out " ) ; g_amd64 = $( sed -n 's/^amd64=//p' <<< " $out " ) ; g_arm64 = $( sed -n 's/^arm64=//p' <<< " $out " )
[ " $( tag_digest " $1 " ) " = " $g_digest " ] || die " $1 changed while it was being read; try again"
}
ref = " $repo : $tag "
read_tag " $ref "
before_index = $g_digest ; kind = $g_kind ; amd64 = $g_amd64 ; had_arm64 = $g_arm64
case " $kind " in
index) ;;
single)
[ " $( arch_of " $repo @ $before_index " ) " = amd64 ] || die " $ref is a single manifest that is not linux/amd64"
amd64 = $before_index ;;
*) die " $ref is neither an index nor an image manifest" ;;
esac
[ " $( wc -w <<< " $amd64 " ) " -eq 1 ] || die " $ref has ' $( wc -w <<< " $amd64 " ) ' linux/amd64 entries, want exactly one"
[[ $amd64 = ~ $dre ]] || die " $ref : malformed amd64 digest ' $amd64 '"
note " $ref index= $before_index amd64= $amd64 existing-arm64=' ${ had_arm64 :- none } '"
if [ -n " $expect " ] && [ " $expect " != " $before_index " ] ; then
die " $ref is now $before_index but the plan was made for $expect : the tag moved, refusing to overwrite it"
fi
if [ -n " $had_arm64 " ] && [ " $force " != 1 ] ; then
die " $ref already has a linux/arm64 entry ( $had_arm64 ); use --force to replace it" 3
fi
if [ -n " $arm64 " ] ; then
[ " $arm64 " != " $amd64 " ] || die "arm64 digest equals the amd64 digest"
[ " $( arch_of " $repo @ $arm64 " ) " = arm64 ] || die " $repo @ $arm64 does not inspect as linux/arm64; refusing to publish"
fi
emit() { # key=value to stdout and $GITHUB_OUTPUT
echo " $1 " ; if [ -n " ${ GITHUB_OUTPUT :- } " ] ; then echo " $1 " >>" $GITHUB_OUTPUT " ; fi
}
emit "before_index= $before_index " ; emit "amd64= $amd64 "
if [ " $plan_only " = 1 ] ; then emit "platforms=plan-only" ; exit 0; fi
# Sources: keep the whole current index (amd64 + its attestation, byte-identical descriptors),
# unless the arm64 entry is being replaced (--force): then only the amd64 manifest is carried over.
if [ " $kind " = index ] && [ -z " $had_arm64 " ] ; then src_old = " $repo @ $before_index " ; else src_old = " $repo @ $amd64 " ; fi
note "creating $ref from $src_old + $repo @ $arm64 "
2026-11-19 21:11:26 -08:00
it create -t " $ref " " $src_old " " $repo @ $arm64 " || { echo "::error::attach-arm64-index: create failed; tag state unverified (was $before_index )" >& 2; exit 1; }
2026-11-19 21:03:27 -08:00
read_tag " $ref "
after_index = $g_digest
ok = 1
[ " $g_kind " = index ] || ok = 0
[ " $g_amd64 " = " $amd64 " ] || ok = 0
[ " $( wc -w <<< " $g_arm64 " ) " -eq 1 ] || ok = 0
if [ " $ok " != 1 ] ; then
2026-11-19 21:11:26 -08:00
echo "::error::attach-arm64-index: $ref after create: kind= $g_kind amd64=' $g_amd64 ' arm64=' $g_arm64 ' (want amd64 $amd64 unchanged + one arm64)" >& 2
# Restore ONLY when our create demonstrably lost the amd64 entry. If the tag now carries a
# different amd64 (a build-push published meanwhile) it is newer than anything we hold: never
# roll it back.
if [ " $kind " = index ] && [ -z " $g_amd64 " ] ; then
echo "::error::attach-arm64-index: amd64 entry lost; restoring $before_index " >& 2
2026-11-19 21:03:27 -08:00
it create -t " $ref " " $repo @ $before_index " || echo "::error::attach-arm64-index: RESTORE FAILED, $ref needs manual repair (previous index $before_index )" >& 2
2026-11-19 21:11:26 -08:00
if [ " $( tag_digest " $ref " ) " = " $before_index " ] ; then echo "attach-arm64-index: restored $before_index " >& 2
else echo "::error::attach-arm64-index: after restore $ref is NOT $before_index ; manual repair needed" >& 2; fi
elif [ " $g_amd64 " != " $amd64 " ] ; then
echo "::error::attach-arm64-index: $ref moved to a different amd64 ( $g_amd64 ) while attaching; NOT restoring (it is newer). Re-check the tag and re-run." >& 2
else
echo "::error::attach-arm64-index: tag state unexpected; NOT restoring automatically. Previous index was $before_index ." >& 2
2026-11-19 21:03:27 -08:00
fi
exit 1
fi
note " $ref now index= $after_index (was $before_index ); amd64 manifest unchanged $amd64 ; arm64= $g_arm64 "
emit "after_index= $after_index " ; emit "platforms=linux/amd64,linux/arm64"
2026-11-19 21:11:26 -08:00
# Alias tag (e.g. latest == php85): re-point only if it was an exact alias of the tag before.
if [ -n " $follow " ] ; then
fdig = $( tag_digest " $repo : $follow " )
if [ " $fdig " = " $before_index " ] ; then
note " $repo : $follow was an alias of $tag ( $before_index ): re-pointing it to $after_index "
it create -t " $repo : $follow " " $repo @ $after_index "
[ " $( tag_digest " $repo : $follow " ) " = " $after_index " ] || die " $repo : $follow does not equal $after_index after the re-point"
emit "followed_tag= $follow "
else
echo "::warning::attach-arm64-index: $repo : $follow is ' ${ fdig :- missing } ', not an alias of $tag ( $before_index ): left untouched"
fi
fi