Scenarios & risk checklist
Cross-border docker pull fails in predictable ways: rate limits (HTTP 429), transient upstream errors (502/503), token expiry mid-pipeline, disk pressure from layer caches, and TLS or proxy mismatches on shared runners. Before tuning concurrency, write down which scenario dominates—otherwise you will optimize the wrong knob.
On remote Mac fleets, symptoms overlap: a job looks “CPU idle” while layers stall, another job spikes APFS fragmentation, and a third burns retries against the same registry shard. Tag incidents with 429-heavy, 5xx-heavy, auth, or disk so weekly reviews can move one lever at a time instead of resetting the whole daemon profile.
max-concurrent-downloads setting starves co-located jobs and amplifies SSD latency—treat pulls as a pooled resource.Use the matrix table in the next sections as acceptance criteria: if 429 rate rises after raising concurrency, revert one step and lengthen backoff, do not add retries without jitter.
Authentication & least privilege
GHCR typically uses a GitHub PAT with read:packages (classic) or a fine-grained token limited to the repositories that publish images. Private registries (Harbor, cloud vendor registries, self-hosted distribution) should receive pull-only robot accounts or short-lived OIDC tokens where the registry supports it.
On shared remote Mac hosts, avoid leaving long-lived credentials in a world-readable ~/.docker/config.json. Prefer per-job login with a secret injected into the shell, then docker logout in a trap, or use a credential helper bound to the CI user keychain with narrow ACLs.
Compare GHCR versus a private registry through an auth lens: GitHub’s model couples org membership, package visibility, and PAT scopes; enterprise Harbor-style servers often expose robot accounts and retention policies that are easier to audit but harder to wire for developers who only know GitHub SSO. Pick the flow that minimizes standing privileges, then standardize one rotation runbook for the whole pool.
- Never reuse a personal admin PAT across teams; rotation becomes a production incident.
- Scope tokens to the smallest package namespace; separate CI read from release write.
- Rotate on a calendar shorter than the vendor maximum TTL so drift alerts fire before hard expiry.
Cross-border network & registry endpoint comparison
Choosing between ghcr.io and a private relay is a latency, compliance, and operational trade-off—not only “which is faster.” Use the table to pick a primary endpoint and a documented fallback.
| Endpoint class | Strengths | Weaknesses | Best when |
|---|---|---|---|
| GHCR (ghcr.io) | Native GitHub identity, OIDC integration in Actions, no mirror to operate. | Cross-region latency; shared public rate limits without enterprise contracts. | Images already published on GitHub; US/EU runners close to edge. |
| Vendor private registry (same cloud region as runner) | Predictable egress billing; regional SLA; private link options. | Extra replication or promotion steps from GHCR. | Compliance requires data residency near the Mac fleet. |
| Pull-through cache / Harbor proxy | One warm cache for many jobs; can absorb bursts if disk is sized. | Single point of failure unless clustered; cache poisoning policies must be explicit. | Many builders share layers; cross-border link is expensive or unstable. |
Latency is only half the story: egress cost and failure isolation matter when a single saturated link blocks every product line. Document a primary path (for example vendor registry in-region) and a cold-start fallback (GHCR with stricter concurrency) so on-call does not improvise during outages.
Executable parameter matrix (defaults you can paste)
The row sets below are starting points for remote Mac CI. Measure registry 429 rate, pull p95, and disk latency for one week before moving to the “aggressive” column.
| Runner profile | Concurrent layer pulls | docker login token TTL / refresh |
HTTP 429 backoff ladder (s, + jitter) | HTTP 5xx / connect backoff ladder (s, cap) | Disk watermarks (warn / throttle / hard stop) |
|---|---|---|---|---|---|
| Conservative (shared pool, weak WAN) | max-concurrent-downloads: 2 · BuildKit max parallelism 2 |
Fine-grained PAT wall-clock 30–60d; job token ≤6h; re-login each job | Respect Retry-After; else 4 → 8 → 16 → 32 → 64 (max 120) |
1 → 3 → 9 → 27 → 60 (max 300) | 80% / 85% / 90% used on data volume; keep ≥18 GB free |
| Balanced (NVMe, stable egress) | max-concurrent-downloads: 3–4 · BuildKit parallelism 4 |
PAT 60–90d with calendar rotation at 50% TTL; weekly drift check | 2 → 4 → 8 → 16 → 32 (max 90) | 1 → 2 → 6 → 18 → 45 (max 180) | 82% / 87% / 92%; keep ≥25 GB free |
| Aggressive (dedicated Mac, same-region mirror) | max-concurrent-downloads: 5–6 only if p95 disk queue stable |
Short-lived robot token 12–24h + automated midnight refresh | 1 → 2 → 4 → 8 → 16 (max 60) — only safe behind your cache | 0.5 → 1 → 3 → 9 (max 60) | 85% / 90% / 93% with proactive image prune between jobs |
Implementation notes: set Docker Engine max-concurrent-downloads in daemon JSON; cap BuildKit layer parallelism via environment (for example BUILDKIT_MAX_PARALLELISM=4) where your stack supports it. Encode the backoff ladder in a thin wrapper around docker pull or your orchestrator retry policy so every team does not fork different numbers.
For broader pull tuning (Git plus Docker), keep the companion playbook in build pool concurrent pull & disk FAQ open beside this page.
CI integration steps (command placeholders)
Adapt names to your orchestrator; placeholders use ALL_CAPS so you can search-replace.
- Disk gate:
df -h "$WORKSPACE_ROOT"— exit non-zero if used% ≥ THROTTLE_PERCENT from the matrix. - Authenticate:
echo "$REGISTRY_TOKEN" | docker login REGISTRY_HOST -u REGISTRY_USER --password-stdin - Pull with digest pin:
docker pull REGISTRY_HOST/NAMESPACE/IMAGE@sha256:IMAGE_DIGEST - Verify:
docker image inspect REGISTRY_HOST/NAMESPACE/IMAGE@sha256:IMAGE_DIGEST --format '{{.Id}}' - Cleanup trap:
docker logout REGISTRY_HOSTand optionaldocker image prune -f --filter "until=24h"when disk > WARN_PERCENT.
For OpenClaw-style stacks that already bundle Docker guidance, cross-link OpenClaw Docker on remote Mac after you wire registry auth.
FAQ: stuck pulls, certificates, proxies
Pull “hangs” at a layer. Lower max-concurrent-downloads, confirm MTU and HTTP/2 through the corporate proxy, and set an explicit low-speed timeout in your wrapper (fail fast, then retry with the 5xx ladder).
Certificate errors. Import the registry CA to the system keychain and Docker’s trust store; align the hostname in docker pull with the cert SAN. Mixed IP access and DNS names is a frequent false “MITM” signal.
Proxy path. Export HTTPS_PROXY consistently for daemon and CLI; allow-list ghcr.io, *.github.com, and your private registry host. If auth succeeds but blobs stall, test direct blob URLs from the runner with curl --http1.1 -I to detect broken middleboxes.
Summary: choose endpoints, cap concurrency, buy predictable capacity
Pick GHCR when identity and publishing already live on GitHub and latency is acceptable; move to a same-region private registry or pull-through cache when compliance, burst stability, or cross-border cost dominates. Pair least-privilege tokens with the TTL row from the matrix, enforce disk watermarks before pulls, and centralize 429/5xx backoff so retries do not stampede.
When you need dedicated Apple Silicon capacity with room to place caches and tune daemon settings yourself, use pricing and purchase pages, browse the help center, or continue reading on the technical blog and homepage—all accessible without logging in.
Remote Mac CI with room for registry tuning
Mac Mini class nodes—SSH/VNC, predictable disks, and policies you control. Compare plans or read more guides; no login required.