Configure remote repository authentication to Docker Hub Stay organized with collections Save and categorize content based on your preferences.
This document describes how to configure authentication to Docker Hub upstreamrepositories for Artifact Registry remote repositories.
We recommend authenticating to Docker Hub even if you are only using publicimages, as authenticating will increase your download rate limit. For moreinformation on Docker Hub download rate limits, seeDocker Hub rate limit. Remote repositories allowyou to add your Docker Hub username and a personal access token saved as asecret to authenticate to Docker Hub.
This document assumes you have already created an Artifact Registry Dockerremote repository, and aDocker Hub account.
For more information on remote repositories, see theRemote repositories overview.
Required roles
To get the permissions that you need to configure authentication to Docker Hub for remote repositories, ask your administrator to grant you the following IAM roles on the project:
- Artifact Registry Admin (
roles/artifactregistry.admin) - Secret Manager Admin (
roles/secretmanager.admin)
For more information about granting roles, seeManage access to projects, folders, and organizations.
You might also be able to get the required permissions throughcustom roles or otherpredefined roles.
Create a Docker Hub personal access token
- Sign in toDocker Hub.
- Create a personalaccess token withread-only permissions.
Copy the access token.
Warning: The access token is only displayed once. If you close the windowit can't be retrieved and you have to create a new access token.Save the access token in a text file in your local or Cloud Shell.
Warning: Treat access tokens like passwords and keep them secure.
Save your personal access token in a secret version
- Create a secret in Secret Manager.
- Save your Docker Hub personal access token as asecret version.
Grant the Artifact Registry service account access to your secret
The Artifact Registry service agent acts on behalf of Artifact Registry when interactingwith Google Cloud services. To allow the service agent to use secretsstored in Secret Manager, you must grant the service agent permissionto view your secret version.
The service agent identifier is:
service-PROJECT-NUMBER@gcp-sa-artifactregistry.iam.gserviceaccount.com
PROJECT-NUMBER is theproject numberof the Google Cloud project where Artifact Registry is running.
To grant the Artifact Registry service agent theSecret Manager Secret Accessorrole:
Console
Go to theSecret Manager page in the Google Cloud console.
On theSecret Manager page, click the checkbox next to the name of the secret.
If it is not already open, clickShow Info Panel to open the panel.
In the info panel, clickAdd Principal.
In theNew principals text area, enter the email address(es) of the members to add.
In theSelect a role dropdown, chooseSecret Manager and thenSecret Manager Secret Accessor.
gcloud
$gcloud secrets add-iam-policy-bindingsecret-id \ --member="member" \ --role="roles/secretmanager.secretAccessor"Wheremember is anIAM member, such as a user, group, or service account.
C#
To authenticate to Artifact Registry, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.
usingGoogle.Cloud.SecretManager.V1;usingGoogle.Cloud.Iam.V1;publicclassIamGrantAccessSample{publicPolicyIamGrantAccess(stringprojectId="my-project",stringsecretId="my-secret",stringmember="user:foo@example.com"){// Create the client.SecretManagerServiceClientclient=SecretManagerServiceClient.Create();// Build the resource name.SecretNamesecretName=newSecretName(projectId,secretId);// Get current policy.Policypolicy=client.GetIamPolicy(newGetIamPolicyRequest{ResourceAsResourceName=secretName,});// Add the user to the list of bindings.policy.AddRoleMember("roles/secretmanager.secretAccessor",member);// Save the updated policy.policy=client.SetIamPolicy(newSetIamPolicyRequest{ResourceAsResourceName=secretName,Policy=policy,});returnpolicy;}}Go
To authenticate to Artifact Registry, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.
import("context""fmt""io"secretmanager"cloud.google.com/go/secretmanager/apiv1")// iamGrantAccess grants the given member access to the secret.funciamGrantAccess(wio.Writer,name,memberstring)error{// name := "projects/my-project/secrets/my-secret"// member := "user:foo@example.com"// Create the client.ctx:=context.Background()client,err:=secretmanager.NewClient(ctx)iferr!=nil{returnfmt.Errorf("failed to create secretmanager client: %w",err)}deferclient.Close()// Get the current IAM policy.handle:=client.IAM(name)policy,err:=handle.Policy(ctx)iferr!=nil{returnfmt.Errorf("failed to get policy: %w",err)}// Grant the member access permissions.policy.Add(member,"roles/secretmanager.secretAccessor")iferr=handle.SetPolicy(ctx,policy);err!=nil{returnfmt.Errorf("failed to save policy: %w",err)}fmt.Fprintf(w,"Updated IAM policy for %s\n",name)returnnil}Java
To authenticate to Artifact Registry, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.
importcom.google.cloud.secretmanager.v1.SecretManagerServiceClient;importcom.google.cloud.secretmanager.v1.SecretName;importcom.google.iam.v1.Binding;importcom.google.iam.v1.GetIamPolicyRequest;importcom.google.iam.v1.Policy;importcom.google.iam.v1.SetIamPolicyRequest;importjava.io.IOException;publicclassIamGrantAccess{publicstaticvoidiamGrantAccess()throwsIOException{// TODO(developer): Replace these variables before running the sample.StringprojectId="your-project-id";StringsecretId="your-secret-id";Stringmember="user:foo@example.com";iamGrantAccess(projectId,secretId,member);}// Grant a member access to a particular secret.publicstaticvoidiamGrantAccess(StringprojectId,StringsecretId,Stringmember)throwsIOException{// Initialize client that will be used to send requests. This client only needs to be created// once, and can be reused for multiple requests. After completing all of your requests, call// the "close" method on the client to safely clean up any remaining background resources.try(SecretManagerServiceClientclient=SecretManagerServiceClient.create()){// Build the name from the version.SecretNamesecretName=SecretName.of(projectId,secretId);// Request the current IAM policy.PolicycurrentPolicy=client.getIamPolicy(GetIamPolicyRequest.newBuilder().setResource(secretName.toString()).build());// Build the new binding.Bindingbinding=Binding.newBuilder().setRole("roles/secretmanager.secretAccessor").addMembers(member).build();// Create a new IAM policy from the current policy, adding the binding.PolicynewPolicy=Policy.newBuilder().mergeFrom(currentPolicy).addBindings(binding).build();// Save the updated IAM policy.client.setIamPolicy(SetIamPolicyRequest.newBuilder().setResource(secretName.toString()).setPolicy(newPolicy).build());System.out.printf("Updated IAM policy for %s\n",secretId);}}}Node.js
To authenticate to Artifact Registry, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.
/** * TODO(developer): Uncomment these variables before running the sample. */// const name = 'projects/my-project/secrets/my-secret';// const member = 'user:you@example.com';//// NOTE: Each member must be prefixed with its type. See the IAM documentation// for more information: https://cloud.google.com/iam/docs/overview.// Imports the Secret Manager libraryconst{SecretManagerServiceClient}=require('@google-cloud/secret-manager');// Instantiates a clientconstclient=newSecretManagerServiceClient();asyncfunctiongrantAccess(){// Get the current IAM policy.const[policy]=awaitclient.getIamPolicy({resource:name,});// Add the user with accessor permissions to the bindings list.policy.bindings.push({role:'roles/secretmanager.secretAccessor',members:[member],});// Save the updated IAM policy.awaitclient.setIamPolicy({resource:name,policy:policy,});console.log(`Updated IAM policy for${name}`);}grantAccess();PHP
To authenticate to Artifact Registry, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.
// Import the Secret Manager client library.use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient;// Import the Secret Manager IAM library.use Google\Cloud\Iam\V1\Binding;use Google\Cloud\Iam\V1\GetIamPolicyRequest;use Google\Cloud\Iam\V1\SetIamPolicyRequest;/** * @param string $projectId Your Google Cloud Project ID (e.g. 'my-project') * @param string $secretId Your secret ID (e.g. 'my-secret') * @param string $member Your member (e.g. 'user:foo@example.com') */function iam_grant_access(string $projectId, string $secretId, string $member): void{ // Create the Secret Manager client. $client = new SecretManagerServiceClient(); // Build the resource name of the secret. $name = $client->secretName($projectId, $secretId); // Get the current IAM policy. $policy = $client->getIamPolicy((new GetIamPolicyRequest)->setResource($name)); // Update the bindings to include the new member. $bindings = $policy->getBindings(); $bindings[] = new Binding([ 'members' => [$member], 'role' => 'roles/secretmanager.secretAccessor', ]); $policy->setBindings($bindings); // Build the request. $request = (new SetIamPolicyRequest) ->setResource($name) ->setPolicy($policy); // Save the updated policy to the server. $client->setIamPolicy($request); // Print out a success message. printf('Updated IAM policy for %s', $secretId);}Python
To authenticate to Artifact Registry, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.
defiam_grant_access(project_id:str,secret_id:str,member:str)->iam_policy_pb2.SetIamPolicyRequest:""" Grant the given member access to a secret. """# Import the Secret Manager client library.fromgoogle.cloudimportsecretmanager# Create the Secret Manager client.client=secretmanager.SecretManagerServiceClient()# Build the resource name of the secret.name=client.secret_path(project_id,secret_id)# Get the current IAM policy.policy=client.get_iam_policy(request={"resource":name})# Add the given member with access permissions.policy.bindings.add(role="roles/secretmanager.secretAccessor",members=[member])# Update the IAM Policy.new_policy=client.set_iam_policy(request={"resource":name,"policy":policy})# Print data about the secret.print(f"Updated IAM policy on{secret_id}")Ruby
To authenticate to Artifact Registry, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.
# project_id = "YOUR-GOOGLE-CLOUD-PROJECT" # (e.g. "my-project")# secret_id = "YOUR-SECRET-ID" # (e.g. "my-secret")# member = "USER-OR-ACCOUNT" # (e.g. "user:foo@example.com")# Require the Secret Manager client library.require"google/cloud/secret_manager"# Create a Secret Manager client.client=Google::Cloud::SecretManager.secret_manager_service# Build the resource name of the secret.name=client.secret_pathproject:project_id,secret:secret_id# Get the current IAM policy.policy=client.get_iam_policyresource:name# Add new member to current bindingspolicy.bindings <<Google::Iam::V1::Binding.new(members:[member],role:"roles/secretmanager.secretAccessor")# Update IAM policynew_policy=client.set_iam_policyresource:name,policy:policy# Print a success message.puts"Updated IAM policy for#{secret_id}"API
Note: Unlike the other examples, this replaces the entire IAM policy.
$curl "https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id:setIamPolicy" \ --request "POST" \ --header "authorization: Bearer $(gcloud auth print-access-token)" \ --header "content-type: application/json" \ --data "{\"policy\": {\"bindings\": [{\"members\": [\"member\"], \"role\": \"roles/secretmanager.secretAccessor\"}]}}"For more information on granting or revoking access to secrets, seeManage access to secrets.
Add Docker Hub credentials to your remote repository
To update your remote repository with your Docker Hub credentials:
Console
Open theRepositories page in the Google Cloud console.
In the repository list, select the repository and clickEdit Repository.
In theRemote repository authentication mode section, update or addyour Docker Hub username and the secret version containing your Docker Hubaccess token.
gcloud CLI
To update your remote repository with your Docker Hub credentials, run thefollowing command:
gcloud artifacts repositories updateREPOSITORY \ --project=PROJECT_ID \ --location=LOCATION \ --remote-username=USERNAME \ --remote-password-secret-version=projects/SECRET_PROJECT_ID/secrets/SECRET_ID/versions/SECRET_VERSIONReplace the following:
REPOSITORYwith the name of your Artifact Registry remoterepository.PROJECT_IDwith your Google Cloud project ID.LOCATIONwith the regional or multi-regionallocation for the repository. You canomit this flag if you set adefault. To view a listof supported locations, run the commandgcloud artifacts locations list.USERNAMEwith your Docker Hub username.SECRET_PROJECT_IDwith the project ID of theGoogle Cloud project in which you created your secret.SECRET_IDwith the name you gave your secret.SECRET_VERSIONwith the secret version you saved yourDocker Hub access token in.
Your credentials are used the next time the remote repository sends a requestfor an artifact from the upstream source.
What's next
- Learn more about Artifact Registryrepositories.
- Pull images with Docker.
- Take the Docker Hub remote repositoryquickstart.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-19 UTC.