How to Log in with a Remote Docker Registry Using a GitLab Pipeline

Modified on Wed, 29 Mar 2023 at 02:04 PM

You might need to authenticate your pipeline to a remote registry when running CI/CD pipelines in GitLab in order to access the necessary images. A GitLab pipeline can be authenticated to a remote register using one of two methods:

1. CI/CD Using Environment Variables

Step 1: CI/CD Using Environment Variables

Navigate to "Settings" in your GitLab project and choose "CI/CD" from the option. The necessary environment variables for authentication can be added by scrolling down to the "Variables" portion. For instance, you can specify the following environment variables if you use Docker Hub:

DOCKER_USERNAME = your_docker_username
DOCKER_PASSWORD = your_docker_password

Step 2: Utilize environment variables in CI/CD in step two.

Use the environment settings in your.gitlab-ci.yml file to log in to the remote registry. For instance, you can use the code below to log in to Docker Hub:


The environment variables specified in step 1 will be used to authenticate to Docker Hub using this command.

2. Requesting the Cloud-Runner Team to Make the Change

The second method is to request a change to your runner from the Cloud-Runner team ( so that it includes the necessary credentials for the remote registry.

This approach is not advised, though, as all jobs run by this runner will have access to the environment variable, posing a security risk. Only when the first image of your runner is stored on a private registry does it make sense to add the credential directly in the runner.

Using environment variables in your CI/CD pipeline or requesting the Cloud-Runner team to make the modification are the two ways to authenticate a GitLab pipeline to a remote registry.

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons

Feedback sent

We appreciate your effort and will try to fix the article