gcloud auth configure-docker: Registry Auth & CI Errors

Configure Docker to authenticate to Artifact Registry or Container Registry.

gcloud auth configure-docker registers gcloud as a Docker credential helper so docker push/pull to Google registries authenticate using your gcloud identity - no separate docker login.

What it does

The command adds a credential-helper entry to Docker’s config.json for the given registry host. For Artifact Registry you pass the per-region host (us-central1-docker.pkg.dev); with no argument it configures the legacy gcr.io hosts. After running it, Docker uses gcloud’s active credentials automatically.

Common usage

# Configure Docker for an Artifact Registry region
gcloud auth configure-docker us-central1-docker.pkg.dev

# Configure for legacy Container Registry (gcr.io)
gcloud auth configure-docker

# Then push
docker push us-central1-docker.pkg.dev/my-project/repo/my-app:latest

Common error in CI: "denied" because the region host was not configured

docker push fails with "denied: Permission ... denied" or "no basic auth credentials" when configure-docker was run for the wrong host (e.g. plain gcr.io instead of the Artifact Registry region), so Docker has no helper for that registry. Fix: run gcloud auth configure-docker <REGION>-docker.pkg.dev for the exact region in your image path, then push. The active gcloud identity also needs roles/artifactregistry.writer. Re-run after switching service accounts so the helper uses the new identity.

Key options

Related guides