@@ -3,7 +3,8 @@
 #   plan     the version, the targets and the ports to build (scripts/plan-build)
 #   gate     tests/run.sh static; the publish waits for it
 #   build    one leg for each planned port, named "Build <arch>": inputs,
-#            docker build, push by digest, evidence, image suite, digest record
+#            builder, build and push by digest (scripts/build-port),
+#            evidence, image suite, digest record
 #   publish  tags on GHCR only (scripts/publish-ghcr)
 #   hub      copies GHCR tags to Docker Hub (scripts/sync-hub)
 #   report   raises or clears the issues build-<arch>, publish-ghcr, publish-hub
@@ -172,17 +173,6 @@ jobs:
           ref="$(scripts/pick-base-image)"
           echo "base_image=$ref" >> "$GITHUB_OUTPUT"
 
-      # The builder runs this image. A Docker Hub fault takes the same digest
-      # from a mirror.
-      - name: Pick the buildkit image registry
-        id: buildkit
-        env:
-          # tag: buildx-stable-1
-          BUILDKIT_IMAGE: docker.io/moby/buildkit:buildx-stable-1@sha256:cec9f139f45e93c5c69c60f8b07cfad9f43f4ef6b6a6cd917527fea5ff2e3dea
-        run: |
-          ref="$(scripts/pick-base-image --image "$BUILDKIT_IMAGE")"
-          echo "ref=$ref" >> "$GITHUB_OUTPUT"
-
       # The committed lists stay when generation fails. The digest record
       # says which lists the build used.
       - name: Generate the mirror lists
@@ -251,10 +241,14 @@ jobs:
           ALLOW_ANCHOR_DOWNGRADE: ${{ inputs.allow_anchor_downgrade || 'none' }}
         run: scripts/check-anchor-floor "$ARCH" "$ANCHOR"
 
-      - name: Set up Buildx
-        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
-        with:
-          driver-opts: image=${{ steps.buildkit.outputs.ref }}
+      # The builder runs this image. A Docker Hub fault takes the same digest
+      # from a mirror. So does a pull limit that runs out after the pick.
+      - name: Set up the builder
+        id: buildkit
+        env:
+          # tag: buildx-stable-1
+          BUILDKIT_IMAGE: docker.io/moby/buildkit:buildx-stable-1@sha256:cec9f139f45e93c5c69c60f8b07cfad9f43f4ef6b6a6cd917527fea5ff2e3dea
+        run: scripts/build-port builder
 
       - name: Log in to GHCR
         uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
@@ -264,43 +258,40 @@ jobs:
           password: ${{ github.token }}
 
       # No tag here. The digest goes to the publish job after every test below.
+      # A pull limit that runs out after the pick builds once more from the
+      # next registry, and base_image names the registry that the build used.
+      # ⚠ A run: step gets no ACTIONS_RUNTIME_TOKEN, and the gha cache needs
+      # it. github-script starts the script with the environment of an action.
       - name: Build and push by digest
         id: push
-        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          TARGET_IMAGE: ${{ needs.plan.outputs.target_image }}
+          BASE_IMAGE: ${{ steps.base.outputs.base_image }}
+          IMAGE_VERSION: ${{ needs.plan.outputs.version }}
+          SOURCE_COMMIT: ${{ github.sha }}
+          BUILD_DATE: ${{ needs.plan.outputs.build_date }}
+          TRANSPORT: ${{ steps.transport.outputs.transport }}
+          SKIP_SERVERS: ${{ steps.lag.outputs.skip_servers }}
         with:
-          context: ${{ github.workspace }}
-          platforms: ${{ matrix.platform }}
-          build-args: |
-            IMAGE_VERSION=${{ needs.plan.outputs.version }}
-            SOURCE_COMMIT=${{ github.sha }}
-            BUILD_DATE=${{ needs.plan.outputs.build_date }}
-            BASE_IMAGE=${{ steps.base.outputs.base_image }}
-            TRANSPORT=${{ steps.transport.outputs.transport }}
-            SKIP_SERVERS=${{ steps.lag.outputs.skip_servers }}
-          outputs: type=image,name=${{ needs.plan.outputs.target_image }},push-by-digest=true,name-canonical=true,push=true
-          cache-from: type=gha,scope=${{ matrix.arch }}
-          cache-to: type=gha,mode=max,scope=${{ matrix.arch }},ignore-error=true
-          provenance: mode=max
-          sbom: true
+          script: await exec.exec('scripts/build-port', ['push'])
 
       # The databases that the build used, from the bootstrap stage in the
       # builder. The build args are those of the step above, so the stage is
       # the same one.
       - name: Export the databases that the build used
-        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
+        id: snapshot
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          DB_SNAPSHOT: ${{ runner.temp }}/dbsnapshot
+          BASE_IMAGE: ${{ steps.push.outputs.base_image }}
+          IMAGE_VERSION: ${{ needs.plan.outputs.version }}
+          SOURCE_COMMIT: ${{ github.sha }}
+          BUILD_DATE: ${{ needs.plan.outputs.build_date }}
+          TRANSPORT: ${{ steps.transport.outputs.transport }}
+          SKIP_SERVERS: ${{ steps.lag.outputs.skip_servers }}
         with:
-          context: ${{ github.workspace }}
-          platforms: ${{ matrix.platform }}
-          target: dbsnapshot
-          build-args: |
-            IMAGE_VERSION=${{ needs.plan.outputs.version }}
-            SOURCE_COMMIT=${{ github.sha }}
-            BUILD_DATE=${{ needs.plan.outputs.build_date }}
-            BASE_IMAGE=${{ steps.base.outputs.base_image }}
-            TRANSPORT=${{ steps.transport.outputs.transport }}
-            SKIP_SERVERS=${{ steps.lag.outputs.skip_servers }}
-          outputs: type=local,dest=${{ runner.temp }}/dbsnapshot
-          cache-from: type=gha,scope=${{ matrix.arch }}
+          script: await exec.exec('scripts/build-port', ['snapshot'])
 
       # --platform: the pushed index has an attestation manifest next to the
       # image, so a pull with no platform picks the platform of the runner.
@@ -345,7 +336,7 @@ jobs:
           ANCHOR: ${{ steps.anchor.outputs.anchor }}
           TRANSPORT: ${{ steps.transport.outputs.transport }}
           SKIP_SERVERS: ${{ steps.lag.outputs.skip_servers }}
-          BASE_IMAGE: ${{ steps.base.outputs.base_image }}
+          BASE_IMAGE: ${{ steps.push.outputs.base_image }}
           MIRRORLIST: ${{ steps.mirrors.outputs.mirrorlist }}
           BUILT_AT: ${{ needs.plan.outputs.build_date }}
         run: |
 
@@ -23,7 +23,7 @@ Each rule below keeps one of these true for one way it could fail.
 | rule | failure it prevents | where |
 | --- | --- | --- |
 | The bootstrap stage starts from the official Arch Linux image, pinned by digest. No `FROM` names an image that this repository publishes. | A build from its own last output keeps each defect of that output, and nobody can rebuild it without trust in this project first. | `Dockerfile`, `tests/static/10-bootstrap-not-circular.sh` |
-| The build asks for the digest of the base image and of the buildkit image from `docker.io`, then `mirror.gcr.io`. For the base image, a Docker official image, `public.ecr.aws` is third. The same digest is the same bytes. A registry that answers with `ratelimit-remaining: 0` is passed over: its pull limit is used up. ⚠ The limit can run out between the probe and the pull. | One registry outage or one used-up pull limit stops every build. | `scripts/pick-base-image` |
+| The build asks for the digest of the base image and of the buildkit image from `docker.io`, then `mirror.gcr.io`. For the base image, a Docker official image, `public.ecr.aws` is third. The same digest is the same bytes. A registry that answers with `ratelimit-remaining: 0` is passed over: its pull limit is used up. A pull that fails with HTTP 429 or `toomanyrequests` runs once more, from the next registry at the same digest. ⚠ A second failure stops the leg, and the next run picks again. | One registry outage or one used-up pull limit stops every build. Docker Hub does not count the HEAD of the pick, so its limit can run out before the pull. | `scripts/pick-base-image`, `scripts/build-port`, `tests/static/36-build-port.sh` |
 | Each shipped `pacman.conf` sets `SigLevel = Required DatabaseOptional`. No SigLevel is `Never`. | A forged or unsigned package installs. Most ports do not sign their databases, so `DatabaseOptional` is necessary. | `rootfs/*/etc/pacman.conf`, `tests/static/30-signature-checking-on.sh` |
 | A port whose keys are not in `archlinux-keyring` has a keyring pin: the package, its sha256, each trusted fingerprint with its expiry. The package is in the tree. | The port deletes a superseded keyring package from its mirrors, and the build cannot get the trust root. | `bootstrap/keyrings/*.pin`, `bootstrap/any/usr/local/bin/install-port-keyring`, `tests/static/88-keyring-pins-vendored.sh` |
 | After populate, each pinned key that is not expired must be fully valid. | A key at marginal validity signs nothing that pacman accepts. The keyring installs, and the transaction commits nothing. | `install-port-keyring` |
@@ -135,18 +135,22 @@ The steps of a build leg, in order:
 
 1. `scripts/binfmt-register ARCH`: the emulator, with the `F` flag.
 2. `scripts/pick-base-image`: the registry for the base image digest.
-3. `scripts/pick-base-image --image "$BUILDKIT_IMAGE"`: the registry for the buildkit image of the builder.
-4. `scripts/gen-mirrorlist ARCH`: exit 0 writes the lists in the checkout of the runner. Any other exit keeps the committed lists.
-5. `scripts/pick-transport ARCH`: `worker` or `oci`.
-6. `scripts/check-mirror-lag ARCH`: each `drop LIST SERVER` line becomes a `LIST=SERVER` pair of `SKIP_SERVERS`.
-7. `scripts/resolve-anchor ARCH`. ⛔ A port that no server answers for fails here: a red leg, never a green skip.
-8. `scripts/check-anchor-floor ARCH ANCHOR`. An anchor that no tag can carry fails here too.
-9. `docker buildx build`, pushed by digest to the target, with provenance (`mode=max`) and an SBOM. The cache is `type=gha` with `ignore-error=true`.
-10. The `dbsnapshot` target, exported to a directory.
+3. `scripts/gen-mirrorlist ARCH`: exit 0 writes the lists in the checkout of the runner. Any other exit keeps the committed lists.
+4. `scripts/pick-transport ARCH`: `worker` or `oci`.
+5. `scripts/check-mirror-lag ARCH`: each `drop LIST SERVER` line becomes a `LIST=SERVER` pair of `SKIP_SERVERS`.
+6. `scripts/resolve-anchor ARCH`. ⛔ A port that no server answers for fails here: a red leg, never a green skip.
+7. `scripts/check-anchor-floor ARCH ANCHOR`. An anchor that no tag can carry fails here too.
+8. `scripts/build-port builder`: the registry for the buildkit image (`pick-base-image --image "$BUILDKIT_IMAGE"`), its pull, and the builder that runs it.
+9. `scripts/build-port push`: `docker buildx build`, pushed by digest to the target, with provenance (`mode=max`) and an SBOM. The cache is `type=gha` with `ignore-error=true`.
+10. `scripts/build-port snapshot`: the `dbsnapshot` target, exported to a directory.
 11. `scripts/gen-evidence`, with `DB_SNAPSHOT` and `EXPECT_ANCHOR`.
 12. `tests/run.sh image` against the pushed digest.
 13. The artifacts `evidence-<arch>` (90 days) and `digest-<arch>` (7 days).
 
+⭐ Steps 8 to 10 run once more when a pull fails on a used-up pull limit. The second try takes the same digest from the next registry: `pick-base-image --after`. A failure counts when the output has a line with `toomanyrequests` or `429 Too Many Requests`. In a build, that line must also name the repository of the base image, because a server of a mirror list can answer 429 too. Any other failure stops the step at once. The push names the base image it used, and the export and the digest record take that value.
+
+Steps 9 and 10 start the script from `actions/github-script`. A `run:` step gets no `ACTIONS_RUNTIME_TOKEN`, and the `type=gha` cache needs it.
+
 The build args of the Dockerfile: `BASE_IMAGE`, `TRANSPORT` (default `worker`), `SKIP_SERVERS` (default empty), `IMAGE_VERSION`, `SOURCE_COMMIT` and `BUILD_DATE`. Its stages: `bootstrap`, `dbsnapshot` and the final unnamed stage.
 
 `digest-<arch>.json` has the keys `arch`, `platform`, `digest`, `anchor`, `transport`, `skip_servers`, `base_image`, `mirrorlist` (`generated` or `committed`) and `built_at`.
 
@@ -169,6 +169,11 @@ Measured facts only. Each row gives its date and its source: the command, the ru
 | image pins: 5, all current; tag push ages `archlinux:latest` 4 days, `registry:3` 17 days, `busybox:latest` 23 days | 2026-10-16 | `scripts/check-image-pins --max-age 14` |
 | `pick-base-image`: docker.io serves the digest of the base image, and of the buildkit image | 2026-10-16 | `scripts/pick-base-image`, and `scripts/pick-base-image --image` with the buildkit pin of `build-deploy.yml` |
 | `moby/buildkit:buildx-stable-1` at `sha256:cec9f139f45e93c5c69c60f8b07cfad9f43f4ef6b6a6cd917527fea5ff2e3dea`: docker.io and mirror.gcr.io answer 200 with that digest; public.ecr.aws (`docker/moby/buildkit`) and ghcr.io answer 404 | 2026-10-16 | `PROG=m; . scripts/lib.sh; reg_head REGISTRY REPO DIGEST` |
+| Docker Hub counts a GET of a manifest as a pull, and not a HEAD. Over the limit it answers HTTP 429: "You have reached your pull rate limit" | documented | docs.docker.com, Docker Hub usage and limits |
+| a registry over its request limit answers HTTP 429 with the error code `TOOMANYREQUESTS`; the docker client prints it as `toomanyrequests:` | documented | distribution/distribution `registry/api/errcode/register.go` |
+| the leg Build ppc64le: `setup-buildx-action` v4.4.1 ran `docker pull` of the buildkit pin, then `docker buildx create --driver docker-container --driver-opt image=<pin> --use`, then `docker buildx inspect --bootstrap` | 2026-10-16 | run 38930740850, the log of the job |
+| the same leg: `build-push-action` v7.4.0 ran `docker buildx build` with the 6 build args, the gha cache, `--attest type=provenance,mode=max,builder-id=<run URL>/attempts/1` and `--metadata-file`. The push added `--attest type=sbom,disabled=false`; buildx v0.38.0, BuildKit v0.33.1 | 2026-10-16 | run 38930740850, the log of the job |
+| the runner gives `ACTIONS_RUNTIME_TOKEN`, `ACTIONS_RESULTS_URL` and `ACTIONS_CACHE_SERVICE_V2` to a JavaScript action, and not to a `run:` step; buildx reads them for a `type=gha` cache | documented | actions/runner `NodeScriptActionHandler.cs`; docker/buildx `build/opt.go` |
 | pacman 7.1.0, a database that no server gives, through curl: `failed retrieving file` lines, then `failed to synchronize all databases (download library error)` | 2026-10-16 | `pacman -Sy` in the test container with `--network none`, against `file://` and `http://127.0.0.1:9` servers |
 | the same through an XferCommand: only `failed to synchronize all databases (error invoking external downloader)` | 2026-10-16 | the same, with an `XferCommand` |
 | a package that no server gives: through curl `warning: failed to retrieve some files`, then `failed to commit transaction (download library error)`; through an XferCommand `failed to commit transaction (error invoking external downloader)` | 2026-10-16 | `pacman -S`, the same way |
 
@@ -261,6 +261,7 @@ The workflows, the other scripts and the tests read the port table, and need no
 | the GHCR mirror is behind | the build drops it for that run (`drop LIST SERVER` in the log). The image still ships it. Nothing to do |
 | the Worker does not answer | `pick-transport` gives `oci`, and the build stage reads GHCR through pacman-oci. Nothing to do |
 | the base image registry does not answer | `pick-base-image` takes the same digest from `mirror.gcr.io`, or for the base image from `public.ecr.aws`. The buildkit image falls back to `mirror.gcr.io` too. Nothing to do |
+| a pull meets a used-up pull limit (HTTP 429, `toomanyrequests`) | `build-port` runs the step once more with the same digest from the next registry. The log says `met a used-up pull limit`. When the second try fails too, the port waits for the next run. Nothing to do |
 | `publish-hub` is open | the next run copies each missing tag. A failure there never touches GHCR. Check the Docker Hub secrets |
 | `registry-drift` is open | the job `hub` of the next build copies the missing and moved tags. A build with nothing to build runs `hub` too |
 | `status-down` or `pages-stale` is open | read the run of `status.yml` that the issue names, and start it again: `gh workflow run status.yml --ref main` |