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:

Navigate to your User Settings by clicking your avatar and selecting Settings.
Select Access Tokens from the sidebar.
Provide a name, select an expiry date (if desired), and grant the read_registry scope.
Click Create personal access token.
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": {
    "registry.gitlab.com": {
      "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:

image: registry.gitlab.com/my-group/my-image:latest

stages:
  - build

build_job:
  stage: build
  script:
    - docker login registry.gitlab.com -u $CI_REGISTRY_USER -p $CI_JOB_TOKEN
    - docker pull registry.gitlab.com/my-group/my-image:latest
    - # 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:

unit_test:
  stage: test
  image: registry.gitlab.com/my-group/private-test-env:latest
  script:
    - run-unit-tests.sh

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.