#!/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 --tag --arm64 sha256: \ # [--expect-index sha256:] [--force] [--follow-tag ] [--builder ] # attach-arm64-index.sh --repo --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 # 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 :T currently has the very same index digest as # 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. # * --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} repo=""; tag=""; arm64=""; expect=""; force=0; plan_only=0; builder=""; follow="" 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 ;; --follow-tag) follow=${2-}; shift 2 ;; --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 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 if [ -n "$expect" ]; then [[ $expect =~ $dre ]] || die "bad --expect-index '$expect'" 2; fi if [ "$plan_only" != 1 ] && [ -z "$expect" ]; then die "--expect-index is required (the digest the plan step read)" 2; fi bflag=(); [ -n "$builder" ] && bflag=(--builder "$builder") # shellcheck disable=SC2086 it() { $IMAGETOOLS "$1" "${bflag[@]}" "${@:2}"; } # tag_digest : manifest (index) digest of a ref = sha256 of its raw manifest bytes; empty on # failure. (Not `--format {{.Manifest.Digest}}`: the CI runner's buildx 0.13.1 ignores it.) tag_digest() { local h h=$(it inspect --raw "$1" 2>/dev/null | sha256sum | cut -d' ' -f1) || return 0 # sha256 of empty input means the inspect produced nothing [ "$h" = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 ] && return 0 echo "sha256:$h" } # arch_of : 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 : prints "kind=index|single", "amd64=", "arm64=". 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 : 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" it create -t "$ref" "$src_old" "$repo@$arm64" || { echo "::error::attach-arm64-index: create failed; tag state unverified (was $before_index)" >&2; exit 1; } 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 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 it create -t "$ref" "$repo@$before_index" || echo "::error::attach-arm64-index: RESTORE FAILED, $ref needs manual repair (previous index $before_index)" >&2 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 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" # 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