How to Pull Docker Images from Private GitLab Registry with GitLab CI/CD

When working with Docker images in a CI/CD environment, it can often be necessary to pull images from a private registry. In this guide, we’ll look at how to access a private Docker image hosted on the GitLab Container Registry within a GitLab CI/CD pipeline, including authentication for Docker-in-Docker scenarios.

Setting Up Your Credentials

Before you can pull an image from a private registry, you need to ensure that your credentials are set up correctly. GitLab provides the DOCKER_AUTH_CONFIG variable for this purpose.

Step-by-Step Guide

Step 1: Generating a Personal Access Token

A personal access token (PAT) will serve as your authentication method to access the GitLab Container Registry privately.

Create a PAT:

  1. Navigate to your User Settings by clicking your avatar and selecting Settings.
  2. Select Access Tokens from the sidebar.
  3. Provide a name, select an expiry date (if desired), and grant the read_registry scope.
  4. Click Create personal access token.
  5. Securely store the generated token; it won’t be shown again.

Step 2: Base64 Encoding Your Credentials

You need to encode your username and personal access token in base64 format:

# Replace 'my_service_username' with your GitLab username and 'my-gitlab-token' with your PAT.
printf "%s:%s" "my_service_username" "my-gitlab-token" | base64 -w0

This produces an encoded string to use in the next step.

Step 3: Adding DOCKER_AUTH_CONFIG to CI/CD Variables

Construct your DOCKER_AUTH_CONFIG JSON object with the following structure, using your encoded auth string:

  "auths": {
    "": {
      "auth": "<base64-encoded-auth-string>"

Now add this as a variable to your GitLab project under Settings > CI/CD, ensuring you mask and protect it.

Step 4. Pulling an Image in the GitLab CI/CD Pipeline

Within your .gitlab-ci.yml, you can now reference images from your private registry like so:


  - build

  stage: build
    - docker login -u $CI_REGISTRY_USER -p $CI_JOB_TOKEN
    - docker pull
    - # Add steps that make use of your Docker image here...

Sample Scenario: Using Private Images as Build Environments

Below is an example of a CI/CD job that leverages a private image for runtime during the build process:

  stage: test

In this scenario, before running the specified script, the pipeline runner will pull the private Docker image private-test-env from your GitLab Container Registry to use as its environment.

That’s it!

By following these steps, you will have configured your GitLab CI/CD pipeline to securely pull Docker images from your private GitLab Container Registry. Remember to always keep your tokens secure and rotate them periodically to maintain security.

Leave a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.