GitLab Container Registry

Version history
  • The group-level Container Registry was introduced in GitLab 12.10.
  • Searching by image repository name was introduced in GitLab 13.0.
note
If you pull container images from Docker Hub, you can also use the GitLab Dependency Proxy to avoid running into rate limits and speed up your pipelines.

With the Docker Container Registry integrated into GitLab, every GitLab project can have its own space to store its Docker images.

You can read more about Docker Registry at https://docs.docker.com/registry/introduction/.

This document is the user guide. To learn how to enable the Container Registry for your GitLab instance, visit the administrator documentation.

View the Container Registry

You can view the Container Registry for a project or group.

  1. Go to your project or group.
  2. Go to Packages & Registries > Container Registry.

You can search, sort, filter, and delete containers on this page. You can share a filtered view by copying the URL from your browser.

Only members of the project or group can access a private project’s Container Registry.

If a project is public, so is the Container Registry.

View the tags of a specific image

You can view a list of tags associated with a given container image:

  1. Go to your project or group.
  2. Go to Packages & Registries > Container Registry.
  3. Select the container image you are interested in.

This brings up the Container Registry Tag Details page. You can view details about each tag, such as when it was published, how much storage it consumes, and the manifest and configuration digests.

You can search, sort (by tag name), filter, and delete tags on this page. You can share a filtered view by copying the URL from your browser.

Use images from the Container Registry

To download and run a container image hosted in the GitLab Container Registry:

  1. Copy the link to your container image:
    • Go to your project or group’s Packages & Registries > Container Registry and find the image you want.
    • Next to the image name, select Copy.

    Container Registry image URL

  2. Use docker run with the image link:

    docker run [options] registry.example.com/group/project/image [arguments]
    

For more information on running Docker containers, visit the Docker documentation.

Image naming convention

Images follow this naming convention:

<registry URL>/<namespace>/<project>/<image>

If your project is gitlab.example.com/mynamespace/myproject, for example, then your image must be named gitlab.example.com/mynamespace/myproject/my-app at a minimum.

You can append additional names to the end of an image name, up to three levels deep.

For example, these are all valid image names for images within the project named myproject:

registry.example.com/mynamespace/myproject:some-tag
registry.example.com/mynamespace/myproject/image:latest
registry.example.com/mynamespace/myproject/my/image:rc1

Build and push images by using Docker commands

To build and push to the Container Registry, you can use Docker commands.

Authenticate with the Container Registry

Before you can build and push images, you must authenticate with the Container Registry.

To authenticate, you can use:

Both of these require the minimum scope to be:

  • For read (pull) access, read_registry.
  • For write (push) access, write_registry & read_registry.

To authenticate, run the docker command. For example:

   docker login registry.example.com -u <username> -p <token>

Build and push images by using Docker commands

To build and push to the Container Registry:

  1. Authenticate with the Container Registry.

  2. Run the command to build or push. For example, to build:

    docker build -t registry.example.com/group/project/image .
    

    Or to push:

    docker push registry.example.com/group/project/image
    

To view these commands, go to your project’s Packages & Registries > Container Registry.

Build and push by using GitLab CI/CD

Use GitLab CI/CD to build and push images to the Container Registry. Use it to test, build, and deploy your project from the Docker image you created.

Authenticate by using GitLab CI/CD

Before you can build and push images by using GitLab CI/CD, you must authenticate with the Container Registry.

To use CI/CD to authenticate, you can use:

  • The CI_REGISTRY_USER CI/CD variable.

    This variable has read-write access to the Container Registry and is valid for one job only. Its password is also automatically created and assigned to CI_REGISTRY_PASSWORD.

    docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    
  • A CI job token.

    docker login -u $CI_REGISTRY_USER -p $CI_JOB_TOKEN $CI_REGISTRY
    
  • A deploy token with the minimum scope of:
    • For read (pull) access, read_registry.
    • For write (push) access, write_registry.
    docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
    
  • A personal access token with the minimum scope of:
    • For read (pull) access, read_registry.
    • For write (push) access, write_registry.
    docker login -u <username> -p <access_token> $CI_REGISTRY
    

Configure your .gitlab-ci.yml file

You can configure your .gitlab-ci.yml file to build and push images to the Container Registry.

  • If multiple jobs require authentication, put the authentication command in the before_script.
  • Before building, use docker build --pull to fetch changes to base images. It takes slightly longer, but it ensures your image is up-to-date.
  • Before each docker run, do an explicit docker pull to fetch the image that was just built. This is especially important if you are using multiple runners that cache images locally.

    If you use the Git SHA in your image tag, each job is unique and you should never have a stale image. However, it’s still possible to have a stale image if you re-build a given commit after a dependency has changed.

  • Don’t build directly to the latest tag because multiple jobs may be happening simultaneously.

Container Registry examples with GitLab CI/CD

If you’re using Docker-in-Docker on your runners, this is how your .gitlab-ci.yml should look:

build:
  image: docker:19.03.12
  stage: build
  services:
    - docker:19.03.12-dind
  script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker build -t $CI_REGISTRY/group/project/image:latest .
    - docker push $CI_REGISTRY/group/project/image:latest

You can also make use of other CI/CD variables to avoid hard-coding:

build:
  image: docker:19.03.12
  stage: build
  services:
    - docker:19.03.12-dind
  variables:
    IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
  script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker build -t $IMAGE_TAG .
    - docker push $IMAGE_TAG

Here, $CI_REGISTRY_IMAGE would be resolved to the address of the registry tied to this project. Since $CI_COMMIT_REF_NAME resolves to the branch or tag name, and your branch name can contain forward slashes (for example, feature/my-feature), it is safer to use $CI_COMMIT_REF_SLUG as the image tag. This is due to that image tags cannot contain forward slashes. We also declare our own variable, $IMAGE_TAG, combining the two to save us some typing in the script section.

Here’s a more elaborate example that splits up the tasks into 4 pipeline stages, including two tests that run in parallel. The build is stored in the container registry and used by subsequent stages, downloading the image when needed. Changes to main also get tagged as latest and deployed using an application-specific deploy script:

image: docker:19.03.12
services:
  - docker:19.03.12-dind

stages:
  - build
  - test
  - release
  - deploy

variables:
  # Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled
  DOCKER_HOST: tcp://docker:2376
  DOCKER_TLS_CERTDIR: "/certs"
  CONTAINER_TEST_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
  CONTAINER_RELEASE_IMAGE: $CI_REGISTRY_IMAGE:latest

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

build:
  stage: build
  script:
    - docker build --pull -t $CONTAINER_TEST_IMAGE .
    - docker push $CONTAINER_TEST_IMAGE

test1:
  stage: test
  script:
    - docker pull $CONTAINER_TEST_IMAGE
    - docker run $CONTAINER_TEST_IMAGE /script/to/run/tests<