Configuring GitLab Runner to Pull Images from a Private Docker Registry

During a GitLab CI practice a student encountered a permission error when the runner tried to download an image from a private registry. On a VM or physical machine the issue can be solved by running docker login , but when the runner itself runs inside Docker (Docker‑in‑Docker) the authentication information must be provided through the project or runner configuration.

Note: Pre‑pulling the image to the runner host can speed up jobs; you can set the pull policy to if-not-present .

First, start the runner using Docker and register it with the Docker executor:

## 注册
docker run -itd --rm -v /data/devops/gitlab-runner/config:/etc/gitlab-runner  gitlab/gitlab-runner:v12.9.0 register \
  --non-interactive \
  --executor "docker" \
  --url "http://gitlab.idevops.site/" \
  --registration-token "4qCqD8pEoLzvgzzVn5oy" \
  --description "devops-runner" \
  --tag-list "build,deploy" \
  --run-untagged="true" \
  --locked="false" \
  --docker-image alpine:latest \
  --access-level="not_protected"

## 运行
docker run -itd  \
  --name gitlab-runner \
  --restart=always \
  -v /data/devops/gitlab-runner/config:/etc/gitlab-runner  \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gitlab/gitlab-runner:v12.9.0

To access a private registry you can use two approaches, both requiring the environment variable DOCKER_AUTH_CONFIG to store authentication data:

Job‑level: add DOCKER_AUTH_CONFIG as a job variable in the CI job definition.

Runner‑level (platform‑wide): add DOCKER_AUTH_CONFIG to the runner’s configuration environment variables.

Obtaining Credential Information

Using docker login

docker login registry.example.com:5000 --username my_username --password my_password

Then copy the content of ~/.docker/config.json :

{
  "auths": {
    "192.168.1.200:8088": {
      "auth": "YWRtaW46SGFyYm9yMTIzNDU="
    }
  },
  "HttpHeaders": {
    "User-Agent": "Docker-Client/19.03.5 (linux)"
  }
}

Using Base64 Encoding

echo -n "my_username:my_password" | base64

# example output
bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=

# JSON format
{
    "auths": {
        "registry.example.com:5000": {
            "auth": "(Base64 content from above)"
        }
    }
}

Configuring the Credential Information

Formatted data example:

{"auths": {"192.168.1.200:8088": {"auth": "YWRtaW46SGFyYm9yMTIzNDU="}}}

Project‑level Configuration

Store the authentication JSON as a variable in the project or in the .gitlab-ci.yml file:

stages:
  - test

variables:
  DOCKER_AUTH_CONFIG: '{"auths": {"192.168.1.200:8088": {"auth": "YWRtaW46SGFyYm9yMTIzNDU="}}}'

test:
  stage: test
  tags:
    - build
  image: 192.168.1.200:8088/spinnaker01/spinnaker01-nginx-demo:RELEASE-1.1.1
  script:
    - sleep 20

System‑level (Runner) Configuration

Add the environment variable to the runner’s configuration file:

[[runners]]
  environment = ['DOCKER_AUTH_CONFIG={"auths": {"192.168.1.200:8088": {"auth": "YWRtaW46SGFyYm9yMTIzNDU="}}}']

Testing and Verification

Run a pipeline job that uses the private image to confirm that the runner can pull it successfully.

Reference: GitLab Docs – Using Private Container Registry Images