Create a remote repository to act as a proxy for Docker Hub.
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
roles/resourcemanager.projectCreator), which contains the
resourcemanager.projects.create permission. Learn how to grant
roles.
Verify that billing is enabled for your Google Cloud project.
Enable the Artifact Registry, Secret Manager APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM
role (roles/serviceusage.serviceUsageAdmin), which
contains the serviceusage.services.enable permission. Learn how to grant
roles.
Install the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
To initialize the gcloud CLI, run the following command:
gcloud initIn the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
roles/resourcemanager.projectCreator), which contains the
resourcemanager.projects.create permission. Learn how to grant
roles.
Verify that billing is enabled for your Google Cloud project.
Enable the Artifact Registry, Secret Manager APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM
role (roles/serviceusage.serviceUsageAdmin), which
contains the serviceusage.services.enable permission. Learn how to grant
roles.
Install the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
To initialize the gcloud CLI, run the following command:
gcloud initTo get the permissions that you need to create a Docker Hub remote repository, ask your administrator to grant you the following IAM roles:
roles/artifactregistry.admin)
on the project
roles/secretmanager.admin)
on the project
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
To complete this quickstart, use either Cloud Shell or your local shell.
To launch Cloud Shell, perform the following steps:
Go to Google Cloud console.
Click the Activate Cloud Shell button: 
.
A Cloud Shell session opens inside a frame lower on the console.
You use this shell to run gcloud commands.
To install gcloud CLI and Docker, perform the following steps:
Install the gcloud CLI. To update an existing
installation, run the command gcloud components update.
Install Docker if it is not already installed.
Docker requires privileged access to interact with registries. On Linux or Windows, add the user that you use to run Docker commands to the Docker security group. This step is not required on macOS since Docker Desktop runs on a virtual machine as the root user.
The Docker security group is called docker.
To add your username, run the following command:
sudo usermod -a -G docker ${USER}
The Docker security group is called docker-users.
To add a user from the Administrator command prompt, run the following
command:
net localgroup docker-users DOMAIN\USERNAME /add
Where
Log out and log back in for group membership changes to take effect. If you are using a virtual machine, you may need to restart the virtual machine for membership changes to take effect.
To ensure that Docker is running, run the following Docker command, which returns the current time and date:
docker run --rm busybox date
The --rm flag deletes the container instance on exit.
To prevent using unauthenticated Docker Hub quota, we recommend authenticating to Docker Hub when using remote repositories. Remote repositories allow you to add your Docker Hub username and a personal access token saved as a secret to authenticate to Docker Hub.
Copy the access token.
Save the access token in a text file in your local or Cloud Shell.
Go to the Secret Manager page in the Google Cloud console.
On the Secret Manager page, click Create Secret.
On the Create secret page, under Name, name your secret my-secret
In the Secret value field, enter your Docker Hub personal access token.
Leave the Regions section unchanged.
Click the Create secret button.
gcloud secrets create my-secret --data-file="/path/to/file.txt"
Where /path/to/file.txt is the location of the text file with your personal access token.
Go to the Secret Manager page in the Google Cloud console.
On the Secret Manager page, click the checkbox next to my-secret.
If it is not already open, click Show Info Panel to open the panel.
In the info panel, click Add Principal.
In the New principals text area, enter the email address of the Artifact Registry service account. The Artifact Registry service account email address is formatted in the following way
service-PROJECT-NUMBER@gcp-sa-artifactregistry.iam.gserviceaccount.com
Where PROJECT-NUMBER is your project number.
To find your project number:
Go to the Dashboard page in the Google Cloud console.
Click the Select from drop-down list at the top of the page.
In the Select from window that appears, select your project.
The project ID and project number are displayed on the project Dashboard Project info card.
In the Select a role dropdown, choose Secret Manager and then Secret Manager Secret Accessor.
gcloud secrets add-iam-policy-binding my-secret \
--member="serviceAccount:service-PROJECT-NUMBER@gcp-sa-artifactregistry.iam.gserviceaccount.com" \
--role="roles/secretmanager.secretAccessor"
Where PROJECT-NUMBER is the project number of your project.
To find your project number:
Go to the Dashboard page in the Google Cloud console.
Click the Select from drop-down list at the top of the page.
In the Select from window that appears, select your project.
The project ID and project number are displayed on the project Dashboard Project info card.
Create an Artifact Registry remote repository named
quickstart-docker-hub-remote in location us-central1 with your Docker Hub
credentials by running the following command:
gcloud artifacts repositories create quickstart-docker-hub-remote \
--project=PROJECT_ID \
--repository-format=DOCKER \
--location=us-central1 \
--description="Remote Docker repository" \
--mode=remote-repository \
--remote-repo-config-desc="Docker Hub" \
--remote-docker-repo=DOCKER-HUB \
--remote-username=USERNAME \
--remote-password-secret-version=projects/PROJECT/secrets/my-secret/versions/1
Where:
quickstart-docker-hub-remote is the name of the repository. For
each repository location in a project, repository names must be unique.PROJECT_ID is your project ID. If this flag is omitted,
the current or default project is used.us-central1 is the regional or multi-regional
location for the repository. You can
omit this flag if you set a default. To view a list
of supported locations, run the command gcloud artifacts locations list."Remote Docker repository" is the optional description of your repository.
Do not include sensitive data, since repository descriptions are not
encrypted."Docker Hub" is the optional description for
the external repository configuration for this remote repository.DOCKER-HUB sets the remote repository upstream to the public Docker Hub
upstream.projects/PROJECT/secrets/my-secret/versions/1
is the secret version you created to store your Docker Hub personal access
token.Artifact Registry creates the repository and adds it to the list of repositories.
Before you can push or pull images, configure Docker to use the Google Cloud CLI to authenticate requests to Artifact Registry.
Sign in to gcloud CLI as the user that will run Docker commands.
gcloud auth login
To set up authentication to Docker repositories in the region us-central1,
run the following command:
gcloud auth configure-docker us-central1-docker.pkg.dev
The command updates your Docker configuration. You can now connect with Artifact Registry in your Google Cloud project to push and pull images.
For information about other authentication methods, see Authentication methods.
Sign in to gcloud CLI as the user that will run Docker commands.
gcloud auth login
Pull an image from Docker Hub onto your machine, and into your remote repository with the following command:
docker pull us-central1-docker.pkg.dev/PROJECT/quickstart-docker-hub-remote/busybox:latest
Where:
us-central1 is the remote repository location.us-central1-docker.pkg.dev is the hostname for the Docker repository
you created.:), see
Domain-scoped projects.quickstart-docker-hub-remote is the ID of the repository you created.busybox is the name of the image you want to pull from Docker Hub into
quickstart-docker-hub-remote.latest is the tagged image version you want to pull from Docker Hub.The image is pulled onto your machine and cached in the remote repository. If you pull the same tagged image again, it will be pulled from your remote repository. Your Docker Hub credentials are used.
List the artifacts stored in your remote repository:
gcloud artifacts packages list \
--location=us-central1 \
--repository=quickstart-docker-hub-remote
The output resembles the following:
Listing items under project my-project, location us-central1, repository quickstart-docker-hub-remote.
PACKAGE: busybox
CREATE_TIME: 2023-06-19T18:59:09
UPDATE_TIME: 2023-06-19T18:59:10
To avoid incurring charges to your Google Cloud account for the resources used on this page, follow these steps.
If you want to keep your project and only delete the repository resource, follow the steps in this section. If you want to delete your entire project, follow the steps in Delete your project
Before you remove the repository, ensure that any images you want to keep are available in another location.
To delete the repository:
Open the Repositories page in the Google Cloud console.
In the repository list, select the quickstart-docker-hub-remote repository.
Click Delete.
To delete the quickstart-docker-hub-remote repository, run the following
command:
gcloud artifacts repositories delete quickstart-docker-hub-remote \ --location=us-central1
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-06-09 UTC.