How to authenticate to GitLab's container registry before building a Docker image?

Question

I have a private GitLab project with a pipeline for building and pushing a Docker image. Therefore I have to authenticate to GitLab's Docker registry first.

Research

I read Authenticating to the Container Registry with GitLab CI/CD:

There are three ways to authenticate to the Container Registry via GitLab CI/CD which depend on the visibility of your project.

Available for all projects, though more suitable for public ones:

• Using the special CI_REGISTRY_USER variable: The user specified by this variable is created for you in order to push to the Registry connected to your project. Its password is automatically set with the CI_REGISTRY_PASSWORD variable. This allows you to automate building and deploying your Docker images and has read/write access to the Registry. This is ephemeral, so it’s only valid for one job. You can use the following example as-is:

  docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  

For private and internal projects:

• Using a personal access token: You can create and use a personal access token in case your project is private:

  • For read (pull) access, the scope should be read_registry.
  • For read/write (pull/push) access, use api.

  Replace the <username> and <access_token> in the following example:

     docker login -u <username> -p <access_token> $CI_REGISTRY
  

• Using the GitLab Deploy Token: You can create and use a special deploy token with your private projects. It provides read-only (pull) access to the Registry. Once created, you can use the special environment variables, and GitLab CI/CD will fill them in for you. You can use the following example as-is:

     docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
  

and Container Registry:

With the update permission model we also extended the support for accessing Container Registries for private projects.

Version history

Your jobs can access all container images that you would normally have access to. The only implication is that you can push to the Container Registry of the project for which the job is triggered.

This is how an example usage can look like:

test:
  script:
    - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
    - docker pull $CI_REGISTRY/group/other-project:latest
    - docker run $CI_REGISTRY/group/other-project:latest

I tried the first and the fourth way and I could authenticate.

Question

What are the pros and cons? I guess the third way is for deployment only, not for building and pushing. Same could be for the second way. Is that right?

And why is the fourth way not listed in the other documentation? Is that way deprecated?

Answer 1

I believe the differences are just about user skill and permissions.

The first way anyone can do since the variables are automatically present in a running job.

Second, anyone, with any permissions, can create a personal access token (but has an extra step compared to 1 to create the access token).

Third, someone with the correct permissions could create a deploy key. Deploy keys don't give access to the API like personal access tokens can, and only have permission to pull/read the data in the repository, they cannot write/push.

Fourth option, it allows you to both read/pull container images from the registry, but it also allows you to push to the registry. This is helpful if you have a CI step that builds an app in an image, or anything else where you're generating a container image and want to push it into the registry (so another step in the pipeline can pull it down and use it). My guess is that this option isn't listed with the others since it's meant for the building of container images. You probably could use it like any of the others though.

Answer 2

I prefer the fourth option. A note: "If a user creates one named gitlab-deploy-token, the username and token of the deploy token is automatically exposed to the CI/CD jobs as CI/CD variables: CI_DEPLOY_USER and CI_DEPLOY_PASSWORD respectively.

When creating deploy token, you can grant permission read/write to registry/package registry.

The CI_REGISTRY_PASSWORD is ephemeral so avoid using it if you have multiple deploy jobs (which need to pull private image) run parallel.