Using a private Docker registry with Gitlab CI

Whether you are using it for running the CI pipelines or need to build a Docker image with it as the base, there may be times you wish to use a Docker image or two from a private Docker registry.

When using it on your computer, you would probably access it with a docker login - however this is impossible to do when using the image: in the .gitlab-ci.yml file.

To get round this, you can specify a DOCKER_AUTH_CONFIG CI Variable containing encoded login credentials. You can then use this to docker login within the Pipeline to build an image FROM a private registry.

Note: This blog post assumes you have knowledge in Gitlab CI/CD and an understanding of Docker

In the steps below, replace with the URL to your private Docker registry

  1. If your registry is hosted on Gitlab: Generate a Gitlab Access Token (on the instance where the registry is) which, as a minimum, has read_registry access (if you need to build and push you will also need write_registry).
  2. Make a note of your token and, on your local machine, check it works with docker login -u [username] -p [password/token]
  3. Once verified, generate a base64 encoding of your username and password: echo -n "my_username:my_password" | base64 - make a note of the result
  4. In the Gitlab instance you wish to use your private registry from, make a new CI/CD variable of type 'File' called DOCKER_AUTH_CONFIG - in it, paste the following (replacing both the registry URL and base64 output):
    "auths": {
        "": {
            "auth": "[base64 output]"
  1. You can now use image: in your .gitlab-ci.yaml files
  2. If you are building another docker image that relies on your private registry you can login using the same credentials stored in the variable. Add the following to your .gitlab-ci.yml file before you build the image
- echo "${DOCKER_AUTH_CONFIG}" > ~/.docker/config.json
- docker login

View this post on Github

You might also enjoy…

Mike Street

Written by Mike Street

Mike is a CTO and Lead Developer from Brighton, UK. He spends his time writing, cycling and coding. You can find Mike on Mastodon.