gcloud auth configure-docker: Push Images in CI

By Daniel Zoghalchali·Latchkey

gcloud auth configure-docker writes a credential helper entry into ~/.docker/config.json so the Docker CLI can authenticate to Google registries using your active gcloud credentials. In CI you run it once after authenticating, then docker push and docker pull just work.

Common flags

REGISTRIES - comma-separated hosts, e.g. us-docker.pkg.dev (positional)
--quiet - skip the interactive confirmation prompt (needed in CI)

Example in CI

Configure the helper for an Artifact Registry region, then push.

shell

gcloud auth configure-docker us-central1-docker.pkg.dev --quiet
docker push us-central1-docker.pkg.dev/my-project/my-repo/app:${GITHUB_SHA}

Common errors in CI

denied: Permission "artifactregistry.repositories.uploadArtifacts" denied - SA missing Artifact Registry Writer
unauthorized: authentication failed - configure-docker not run, or wrong registry host
gcloud crashed ... config.json - the docker config dir is unwritable on the runner

Using this in CI

Cloud CLIs behave differently on a runner than on your laptop. They assume no interactive terminal, no cached credentials, and no browser for device-code flows, so the same command that works locally can hang or fail on a runner.

Authenticate with a short-lived OIDC token rather than a long-lived static key. GitHub Actions can exchange id-token: write for cloud credentials with no stored secret.
Always pass the non-interactive flag. Most cloud CLIs will otherwise prompt and hang until the job times out.
Pin the CLI version. Cloud CLIs change output formats between minor releases, and any script parsing that output will break silently.
Set the output format explicitly (--output json) rather than relying on the default, which can differ by version and configuration profile.

Key takeaways

Registers gcloud as a Docker credential helper for Google registries.
Pass the exact registry host (region-aware for Artifact Registry) and --quiet in CI.
Push failures are usually missing IAM roles, not a configure-docker bug.

Frequently asked questions

gcloud auth configure-docker: Push Images in CI?

Example in CI?