Authentication Methods

To authenticate to Container Registry, you should use gcloud as a Docker credential helper as described below.

This page also describes advanced authentication methods.

Before you begin

Make sure that you have:

  1. Installed the most recent version of the Cloud SDK, which includes the gcloud command-line tool

  2. Installed Docker

gcloud as a Docker credential helper

To authenticate to Container Registry, use gcloud as a Docker credential helper. To do so, run the following command:

gcloud auth configure-docker

You need to run this command once to authenticate to Container Registry.

We strongly recommend that you use this method when possible. It provides secure, short-lived access to your project resources.

Advanced authentication methods

The advanced methods on this page should only be used when using gcloud as a Docker credential helper is not ideal, and when you understand the security implications of the advanced method.

The advanced authentication methods are:

Standalone Docker credential helper

Docker needs access to Container Registry to push and pull images. You can use the standalone Docker credential helper tool, docker-credential-gcr, to configure your Container Registry credentials for use with Docker.

The credential helper fetches your Container Registry credentials—either automatically, or from a location specified using its --token-source flag—then writes them to Docker's configuration file. This way, you can use Docker's command-line tool, docker, to interact directly with Container Registry.

To use the Docker credential helper:

  1. Download docker-credential-gcr in one of three ways:

    • Using go get:

      go get -u
    • From the docker-credential-gcr's GitHub releases, optionally using the curl command-line utility. For example:

      OS=linux  # or "darwin" for OSX, "windows" for Windows.
      ARCH=amd64  # or "386" for 32-bit OSs
      curl -L "${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \
        | tar xz --to-stdout docker-credential-gcr \
        > /usr/bin/docker-credential-gcr && chmod +x /usr/bin/docker-credential-gcr
    • Using the gcloud command-line tool:

      gcloud components install docker-credential-gcr
  2. Configure Docker to use your Container Registry credentials when interacting with Container Registry (you are only required to do this once):

    docker-credential-gcr configure-docker

See docker-credential-gcr's main documentation on GitHub for more information.

gcloud docker

Use gcloud docker to inject the Docker client with Container Registry credentials before handing the request off to Docker. For example, to push an image identified by its digest, use the command:

gcloud docker -- push [HOSTNAME]/[PROJECT-ID]/[IMAGE]@[IMAGE_DIGEST]


  • [HOSTNAME] is listed under Location in the console. It's one of four options:,,, or
  • [PROJECT-ID] is your Google Cloud Platform Console project ID). See Domain-scoped projects for how to work with projects IDs that include a domain.
  • [IMAGE] is the image's name in Container Registry.
  • [IMAGE_DIGEST] is the sha256 hash value of the image contents. In the console, click on the specific image to see its metadata. The digest is listed as the Image digest.

See the gcloud docker documentation for more information.

Access token

Access tokens are short-lived tokens that provide read/write access to your Google Cloud Platform resources.

The gcloud docker command authenticates Docker commands by passing a short-lived access token as a password to Container Registry.

  • For docker pull and docker search, the access token must use the devstorage.read_only scope.
  • For docker push, the access token must use the devstorage.read_write scope.

This same scheme can be used in the absence of the gcloud command-line tool by creating an appropriate access token (such as Compute Engine instance metadata).

The access granted by this token is the same as what is granted when using the gcloud docker command to authenticate, making this the safest of the alternative authentication methods.

To use an access token, see the Application Default Credentials documentation. Then, use the following credentials:

Linux / macOS

Username oauth2accesstoken
Password Your access token. For example, gcloud auth print-access-token

For example:

gcloud auth print-access-token | docker login -u oauth2accesstoken --password-stdin

Or, for older Docker clients which don't support --password-stdin:

docker login -u oauth2accesstoken -p "$(gcloud auth print-access-token)"

Username oauth2accesstoken
Password Copy-and-paste the output of gcloud auth print-access-token.

For example:

gcloud auth print-access-token

docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..."

JSON key file

A service account JSON key file is a long-lived credential that is scoped to a specific GCP Console project and its resources.

Service accounts automatically created by GCP, such as the Container Registry service account, are granted the read-write Editor role for your whole project. However, you may wish to grant other service accounts more specific permissions. Configuring Access Control explains the roles that can interact with Container Registry.

You can grant the service account access to the registry containing your Container Registry images.

Alternatively, if a service account is only used for pulling and viewing images, you can set the service account's project-level role to the read-only Viewer from the GCP Console IAM menu. However, the Viewer role has read-only permissions for your whole project and all of its resources, which may not be desired.

To use a JSON key file, follow the service account instructions instructions in the Google Cloud Platform Console Help Center. Then, use the following credentials:

Linux / macOS

Username _json_key (NOT the name of your service account)
Password The contents of the key file you downloaded when creating the service account.

For example:

docker login -u _json_key --password-stdin < keyfile.json

Or, for older Docker clients which don't support --password-stdin:

docker login -u _json_key -p "$(cat keyfile.json)"

Username _json_key (NOT the name of your service account)
Password The contents of the key file you downloaded when creating the service account.

For example:

set /p PASS=<keyfile.json
docker login -u _json_key -p "%PASS%"

See the service accounts documentation to learn more about configuring service accounts.

Was this page helpful? Let us know how we did:

Send feedback about...

Container Registry