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