Docker push verify
After `docker buildx build --push`, always verify the image actually landed on the upstream registry. `buildx exit 0` does not prove the push succeeded — buildx can silently fail on the push step (network stall, expired auth, layer corruption) and still exit 0 without an actual upload. Without verification, a deploy is declared successful while downstream consumers keep pulling the old image.From its SKILL.md
npx -y skills add rustidi98/agent-guardrails --skill docker-push-verifyAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
4.4 KB, as published. Nobody here has run it
Docker Push Verify
Origin: a production incident where
buildx --pushtwice silent-failed without an actual upload. The build reportedexit 0andnaming to ...:latest done, but the registry still held the previous image. A downstream GPU inference service kept failing for an hour untildocker manifest inspectrevealed the truth.
docker buildx build --push has 4 finalization steps:
exporting layers— local manifest packingexporting manifest sha256:...— local manifest hashnaming to <registry>/<image>:<tag> done— local tag, not a pushpushing manifest/pushing layer→ upstream
Steps 1-3 can exit 0 WITHOUT step 4. Especially when:
- Network stall between the Docker VM and the upstream registry
- Auth token expired mid-push (no re-auth happens)
- buildx
tail -Nbuffering hides live progress - Build process killed before push completes (but buildx exits 0 after
naming)
When to Activate
MANDATORY after any:
docker buildx build --pushdocker push <image>- any rebuild script that uses
buildx --pushinternally - any CI/CD job that declares an image deployed
3-Step Verification Protocol
Step 1: Inspect the manifest on upstream
docker manifest inspect <registry>/<org>/<image>:<tag> 2>&1 | head -5
If manifest unknown or not found — the push did NOT happen. Do not declare the deploy successful.
Step 2: Compare timestamp with the build moment
# Example: GitHub Container Registry API
curl -s -u "$USER:$REGISTRY_TOKEN" \
"https://api.github.com/users/$USER/packages/container/$IMAGE/versions?per_page=3" \
| python3 -c "import sys,json; d=json.load(sys.stdin); [print(v['metadata']['container'].get('tags',[]), v['created_at'][:19]) for v in d[:3]]"
Check that created_at matches your build moment (not yesterday's). If the latest tag is stale — the push never landed.
Step 3: Pull via an external pipe and grep for a fix marker
If there is a concrete fix in src/ (e.g. a distinctive comment marker):
docker run --rm --platform linux/amd64 --entrypoint=/bin/sh \
$IMAGE -c 'grep -nc "FIX-MARKER" /app/src/main.py'
If 0 — the fix is not in the image. Push didn't land, or a cache hit reused an old layer.
What to Do on Detected Failure
- Do NOT declare the deploy complete in your report.
- Try
docker push $IMAGEdirectly (shows progress by default) — without going throughbuildx, which buffers the upload. - If a direct push hangs 5+ min — kill it, try splitting the flow:
docker buildx build --load --platform ... .(build to local)docker push <registry>/...:tag(push separately with live progress)
- If pushing to an empty registry for the first time — check
docker login.
Incident Reconstruction
# What was done (WRONG):
bash scripts/rebuild.sh --tag <tag> 2>&1 | tail -60
# Monitor showed:
# #19 naming to <registry>/<image>:latest done
# #19 naming to <registry>/<image>:<tag> done
# Background task exit code 0
# Assumed: "image deployed"
# What should have been done AFTER:
docker manifest inspect <registry>/<image>:<tag>
# → manifest unknown ← push never landed!
curl -u "$USER:$REGISTRY_TOKEN" \
"https://api.github.com/users/$USER/packages/container/<image>/versions" \
| jq '.[0].created_at'
# → stale timestamp ← previous build, not today's
# Fix: direct push
docker push <registry>/<image>:latest
# → "1bfd9b3da406: Pushed" ← now it's real
Anti-Patterns (don't)
- ❌ Rely on
exit code 0from buildx as proof of push - ❌ Rely on the
naming to ... doneevent as proof of push - ❌
| tail -Non buildx — the buffer blocks live progress, causing premature kills - ❌ Assume a cache hit means the image is on upstream (cache lives in local Docker, not the registry)
Quick-Reference One-Liner
After any buildx --push:
docker manifest inspect "$IMAGE" >/dev/null 2>&1 \
&& echo "✅ verified on upstream" \
|| echo "❌ push failed silently — direct docker push needed"