Diagnosing Cloud Run Deployments: Build, Revision, IAM and Runtime Failures
Cloud Run incidents are easiest to resolve when the deployment is treated as a chain of independently testable stages. This field guide turns an ambiguous failed deployment into a short sequence of evidence-backed checks.
Start by locating the failing boundary
Separate source checkout, Cloud Build, Artifact Registry, revision creation, container startup and request invocation. Record the first stage that does not produce its expected artifact. A successful image build does not prove that the revision can start, and a ready revision does not prove that its caller has run.invoker.
Read build evidence before changing configuration
Inspect the failing build step, builder image, substitutions and service account. Reproduce the container build locally when possible and verify that the image is pushed under the digest the deployment references. Avoid changing IAM to solve a compilation or Docker context failure.
Test the container contract
Cloud Run injects PORT; the process must bind to that port on 0.0.0.0 and remain alive. Check startup logs for missing environment variables, migrations, secret access, architecture mismatches and health-check timeouts. Run the same image with production-like environment names but non-production secrets.
Trace identity end to end
Distinguish the build identity, deployment identity, runtime service account and caller identity. Grant each only the roles required at its resource boundary. For a 403, use audit logs to identify the denied principal and permission instead of adding broad Editor access.
Make rollback a normal operation
Keep revisions immutable, tag known-good images by digest and preserve previous traffic targets. A safe pipeline deploys without traffic, verifies readiness, sends a controlled probe and shifts traffic gradually. Rollback should change traffic, not rebuild yesterday's source.
Evidence to retain
For each incident retain the build ID, image digest, revision name, configuration diff, denied permission or startup exception, validation result and remediation owner. That record improves the runbook and provides useful operational and compliance evidence.