Publishing an image does not prove a workload can read it
Artifact Registry stores build artifacts, including container images. A build service can successfully publish an image while a runtime cannot pull it. The writer and reader may live in different projects, use different identities or address different repository paths. Diagnose the failing pull request rather than repeating the build without evidence.
Google's container troubleshooting guide emphasizes the full image path and the account performing the pull. The path includes a registry hostname, project, repository and image reference. A misspelled region hostname or an unexpected project can look like an access problem. Establish the artifact's identity before changing IAM.
Prepare a reproducible artifact handoff
- Create the intended repository and document its location, owning project and retention policy. Distinguish the image-publishing identity from the runtime reader.
- Record an immutable digest for every accepted build. Keep a human-friendly tag if useful, but do not use a mutable label as the only evidence of what was released.
- Test that the intended runtime can pull a non-production fixture while an unrelated identity cannot. Document how the previous accepted image remains available for recovery.
For external Docker clients, client authentication configuration is also relevant. Managed runtime environments have their own identity integration; do not assume the developer's local credential helper is used by a cluster or service.
Illustrative incident: cross-project rollout stalls
A team moves images into a central repository. The build account writes there, but a workload in another project still uses a reader identity without access to that repository. Existing replicas continue running while new ones fail to pull. This is an illustrative scenario. Deleting working replicas would reduce capacity before the artifact access problem is solved.
Compare reference, existence and caller
Capture the exact image reference from the failing workload and compare it with the published artifact. Review the principal that performs the runtime pull; it may differ from the application identity used after startup. Separate an absent tag from a denied read and from a network failure.
| Observation | Check | Decision |
|---|---|---|
| Reference names the wrong repository | Deployment manifest versus build output | Correct release wiring |
| Artifact exists but runtime is denied | Actual reader and repository authorization | Review scoped reader access |
| Local pull works but managed pull fails | Different credentials and execution environments | Test the runtime path |
| New replicas fail, old replicas serve | Rollout state and available capacity | Preserve working capacity during repair |
Use sanitized event excerpts and artifact identifiers in the incident record. Never copy a Docker credential configuration containing authentication material into a shared ticket. Review cross-project ownership with both repository and runtime teams before changing permissions.
Recover the release without bypassing artifact controls
Correct a demonstrated reference error or grant the approved runtime reader the required repository access. Keep publication permissions separate; a workload that reads images does not ordinarily need to overwrite them. If policy blocks the intended path, escalate that decision rather than switching to an uncontrolled public mirror.
Start a new test replica and verify the pulled digest matches the accepted build. Exercise the application through its normal endpoint, then confirm rollout completion. Rehearse pulling the previous accepted digest as well. A successful registry login by an administrator is not the same as a verified application deployment.
Reliability and the handover record
Track image-pull failures, rollout completion and retained recovery artifacts. An illustrative release rule could require the intended runtime to pull the exact candidate digest before traffic is expanded. This is an internal acceptance gate, not an Artifact Registry SLA or a measured availability claim.
The SOP should retain repository owner, writer, reader, image digest, rollout status and reversal target. Escalate changes that grant publication rights or move artifacts across trust boundaries. Review retention rules so cleanup cannot remove the only approved recovery image.
See container engineering for related artifact-to-runtime delivery scope.
Technical reference
Google Cloud: troubleshoot container images and authenticate Docker clients. Reviewed 19 October 2026; validate the specific runtime's pulling identity.