• Enable the Container Registry for your project
• Control Container Registry from within GitLab
  • Control Container Registry for your project
  • Control Container Registry for your group
  • Image Repository details page
• Use images from GitLab Container Registry
• Authenticating to the GitLab Container Registry
• Build and push images from your local machine
• Build and push images using GitLab CI/CD
  • Authenticating to the Container Registry with GitLab CI/CD
  • Container Registry examples with GitLab CI/CD
  • Using a Docker-in-Docker image from your Container Registry
• Delete images
  • Delete images from within GitLab
  • Delete images using the API
  • Delete images using GitLab CI/CD
  • Delete images by using a cleanup policy
• Cleanup policy
  • Managing project cleanup policy through the UI
    • Troubleshooting cleanup policies
  • Managing project cleanup policy through the API
  • Use with external container registries
  • Regex pattern examples
• Use the Container Registry to store Helm Charts
• 制限事項
• Troubleshooting the GitLab Container Registry
  • Docker connection error
  • Troubleshoot as a GitLab server admin
  • Unable to change path or transfer a project

GitLab Container Registry

With the Docker Container Registry integrated into GitLab, every 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/.

Enable the Container Registry for your project

If you cannot find the Packages & Registries > Container Registry entry under your project’s sidebar, it is not enabled in your GitLab instance. Ask your administrator to enable GitLab Container Registry following the administration documentation.

If you are using GitLab.com, this is enabled by default so you can start using the Registry immediately. Currently there is a soft (10GB) size restriction for Registry on GitLab.com, as part of the repository size limit.

Once enabled for your GitLab instance, to enable Container Registry for your project:

1. Go to your project’s Settings > General page.
2. Expand the Visibility, project features, permissions section and enable the Container Registry feature on your project. For new projects this might be enabled by default. For existing projects (prior GitLab 8.8), you will have to explicitly enable it.
3. Press Save changes for the changes to take effect. You should now be able to see the Packages & Registries > Container Registry link in the sidebar.

Control Container Registry from within GitLab

GitLab offers a simple Container Registry management panel. This management panel is available for both projects and groups.

Control Container Registry for your project

Navigate to your project’s Packages & Registries > Container Registry.

This view will:

• Show all the image repositories that belong to the project.
• Allow you to filter image repositories by their name.
• Allow you to delete one or more image repository.
• Allow you to navigate to the image repository details page.
• Show a Quick start dropdown with the most common commands to log in, build and push
• Optionally, a banner will be visible if the cleanup policy is enabled for this project.

Control Container Registry for your group

Navigate to your groups’s Packages & Registries > Container Registry.

This view will:

• Show all the image repositories of the projects that belong to this group.
• Allow to delete one or more image repositories.
• Allow to navigate to a specific image repository details page.

Image Repository details page

Clicking on the name of any image repository will navigate to the details.

This view:

• Shows all the image repository details.
• Shows all the tags of the image repository.
• Allows you to quickly copy the tag path (by clicking on the clipboard button near the tag name).
• Allows you to delete one or more tags.

Use images from GitLab Container Registry

To download and run a container from images hosted in GitLab Container Registry, use docker run:

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

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

Authenticating to the GitLab Container Registry

If you visit the Packages & Registries > Container Registry link under your project’s menu, you can see the explicit instructions to login to the Container Registry using your GitLab credentials.

For example if the Registry’s URL is registry.example.com, then you should be able to login with:

docker login registry.example.com

If a project is private, credentials will need to be provided for authorization. There are two ways to do this:

• By using a personal access token.
• By using a deploy token.

The minimum scope needed for both of them is read_registry.

Example of using a token:

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

Build and push images from your local machine

Building and publishing images should be a straightforward process. Just make sure that you are using the Registry URL with the namespace and project name that is hosted on GitLab:

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

Your image will be named after the following scheme:

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

GitLab supports up to three levels of image repository names. The following examples of image tags are valid:

registry.example.com/group/project:some-tag
registry.example.com/group/project/image:latest
registry.example.com/group/project/my/image:rc1

Build and push images using GitLab CI/CD

While you can build and push your images from your local machine, the true power of the Container Registry comes when you combine it with GitLab CI/CD. You can then create workflows and automate any processes that involve testing, building, and eventually deploying your project from the Docker image you created.

Before diving into the details, some things you should be aware of:

• You must authenticate to the container registry before running any commands. You can do this in the before_script if multiple jobs depend on it.
• Using docker build --pull fetches any changes to base images before building in case your cache is stale. It takes slightly longer, but it means you don’t get stuck without security patches for base images.
• Doing an explicit docker pull before each docker run fetches the latest image that was just built. This is especially important if you are using multiple Runners that cache images locally. Using the Git SHA in your image tag makes this less necessary since each job will be unique and you shouldn’t ever 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.
• You don’t want to build directly to latest tag in case there are multiple jobs happening simultaneously.

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
  

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 similar to this:

build:
  image: docker:19.03.11
  stage: build
  services:
    - docker:19.03.11-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 variables to avoid hard-coding:

build:
  image: docker:19.03.11
  stage: build
  services:
    - docker:19.03.11-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 (e.g., 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 master also get tagged as latest and deployed using an application-specific deploy script:

image: docker:19.03.11
services:
  - docker:19.03.11-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

test2:
  stage: test
  script:
    - docker pull $CONTAINER_TEST_IMAGE
    - docker run $CONTAINER_TEST_IMAGE /script/to/run/another/test

release-image:
  stage: release
  script:
    - docker pull $CONTAINER_TEST_IMAGE
    - docker tag $CONTAINER_TEST_IMAGE $CONTAINER_RELEASE_IMAGE
    - docker push $CONTAINER_RELEASE_IMAGE
  only:
    - master

deploy:
  stage: deploy
  script:
    - ./deploy.sh
  only:
    - master

Using a Docker-in-Docker image from your Container Registry

If you want to use your own Docker images for Docker-in-Docker, there are a few things you need to do in addition to the steps in the Docker-in-Docker section:

1. Update the image and service to point to your registry.
2. Add a service alias.

Below is an example of what your .gitlab-ci.yml should look like:

 build:
   image: $CI_REGISTRY/group/project/docker:19.03.11
   services:
     - name: $CI_REGISTRY/group/project/docker:19.03.11-dind
       alias: docker
   stage: build
   script:
     - docker build -t my-docker-image .
     - docker run my-docker-image /script/to/run/tests

If you forget to set the service alias, the docker:19.03.11 image won’t find the dind service, and an error like the following will be thrown:

error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host

Delete images

You can delete images from your Container Registry in multiple ways.

Delete images from within GitLab

To delete images from within GitLab:

1. Navigate to your project’s or group’s Packages & Registries > Container Registry.

2. From the Container Registry page, you can select what you want to delete, by either:

   • Deleting the entire repository, and all the tags it contains, by clicking the red Trash icon.
   • Navigating to the repository, and deleting tags individually or in bulk by clicking the red Trash icon next to the tag you want to delete.

3. In the dialog box, click Remove tag.

   

Delete images using the API

If you want to automate the process of deleting images, GitLab provides an API. For more information, see the following endpoints:

• Delete a Registry repository
• Delete an individual Registry repository tag
• Delete Registry repository tags in bulk

Delete images using GitLab CI/CD

The following example defines two stages: build, and clean. The build_image job builds the Docker image for the branch, and the delete_image job deletes it. The reg executable is downloaded and used to remove the image matching the $CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG environment variable.

To use this example, change the IMAGE_TAG variable to match your needs:

stages:
  - build
  - clean

build_image:
  image: docker:19.03.11
  stage: build
  services:
    - docker:19.03.11-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
  only:
    - branches
  except:
    - master

delete_image:
  image: docker:19.03.11
  stage: clean
  services:
    - docker:19.03.11-dind
  variables:
    IMAGE_TAG: $CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG
    REG_SHA256: ade837fc5224acd8c34732bf54a94f579b47851cc6a7fd5899a98386b782e228
    REG_VERSION: 0.16.1
  before_script:
    - apk add --no-cache curl
    - curl --fail --show-error --location "https://github.com/genuinetools/reg/releases/download/v$REG_VERSION/reg-linux-amd64" --output /usr/local/bin/reg
    - echo "$REG_SHA256  /usr/local/bin/reg" | sha256sum -c -
    - chmod a+x /usr/local/bin/reg
  script:
    - /usr/local/bin/reg rm -d --auth-url $CI_REGISTRY -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $IMAGE_TAG
  only:
    - branches
  except:
    - master

Delete images by using a cleanup policy

You can create a per-project cleanup policy to ensure older tags and images are regularly removed from the Container Registry.

Cleanup policy

• GitLab 12.8で導入されました。
• Renamed from “expiration policy” to “cleanup policy” in GitLab 13.2.

For a specific project, if you want to remove tags you no longer need, you can create a cleanup policy. When the policy is applied, tags matching the regex pattern are removed. The underlying layers and images remain.

To delete the underlying layers and images no longer associated with any tags, Instance Administrators can use garbage collection with the -m switch.

The cleanup policy algorithm starts by collecting all the tags for a given repository in a list, then goes through a process of excluding tags from it until only the ones to be deleted remain:

1. Collect all the tags for a given repository in a list.
2. Excludes the tag named latest from the list.
3. Evaluates the name_regex, excluding non-matching names from the list.
4. Excludes any tags that do not have a manifest (not part of the options).
5. Orders the remaining tags by created_date.
6. Excludes from the list the N tags based on the keep_n value (Number of tags to retain).
7. Excludes from the list the tags more recent than the older_than value (Cleanup interval).
8. Excludes from the list any tags matching the name_regex_keep value (Images to preserve).
9. Finally, the remaining tags in the list are deleted from the Container Registry.

Managing project cleanup policy through the UI

To manage project cleanup policy, navigate to Settings > CI/CD > Container Registry tag cleanup policy.

The UI allows you to configure the following:

• Cleanup policy: enable or disable the cleanup policy.
• Cleanup interval: how long tags are exempt from being deleted.
• Cleanup schedule: how often the cron job checking the tags should run.
• Number of tags to retain: how many tags to always keep for each image.
• Docker tags with names matching this regex pattern will expire: the regex used to determine what tags should be cleaned up. To qualify all tags for cleanup, use the default value of .*.
• Docker tags with names matching this regex pattern will be preserved: the regex used to determine what tags should be preserved. To preserve all tags, use the default value of .*.

Troubleshooting cleanup policies

If you see the following message:

“Something went wrong while updating the cleanup policy.”

Check the regex patterns to ensure they are valid.

You can use Rubular to check your regex. View some common regex pattern examples.

Managing project cleanup policy through the API

You can set, update, and disable the cleanup policies using the GitLab API.

例：

• Select all tags, keep at least 1 tag per image, clean up any tag older than 14 days, run once a month, preserve any images with the name master and the policy is enabled:

   curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-master"}}' 'https://gitlab.example.com/api/v4/projects/2'
  

See the API documentation for further details: Edit project.

Use with external container registries

When using an external container registry, running a cleanup policy on a project may have some performance risks. If a project is going to run a policy that will remove large quantities of tags (in the thousands), the GitLab background jobs that run the policy may get backed up or fail completely. It is recommended you only enable container cleanup policies for projects that were created before GitLab 12.8 if you are confident the amount of tags being cleaned up will be minimal.

Regex pattern examples

Cleanup policies use regex patterns to determine which tags should be preserved or removed, both in the UI and the API.

Here are examples of regex patterns you may want to use:

• Match all tags:

   .*
  

• Match tags that start with v:

   v.+
  

• Match tags that contain master:

   master
  

• Match tags that either start with v, contain master, or contain release:

   (?:v.+|master|release)
  

Use the Container Registry to store Helm Charts

With the launch of Helm v3, you can use the Container Registry to store Helm Charts. However, due to the way metadata is passed and stored by Docker, it is not possible for GitLab to parse this data and meet performance standards. This epic updates the architecture of the Container Registry to support Helm Charts.

You can read more about the above challenges here.

制限事項

• Moving or renaming existing Container Registry repositories is not supported once you have pushed images, because the images are signed, and the signature includes the repository name. To move or rename a repository with a Container Registry, you will have to delete all existing images.
• Prior to GitLab 12.10, any tags that use the same image ID as the latest tag will not be deleted by the cleanup policy.

Troubleshooting the GitLab Container Registry

Docker connection error

A Docker connection error can occur when there are special characters in either the group, project or branch name. Special characters can include:

• Leading underscore
• Trailing hyphen/dash

To get around this, you can change the group path, change the project path or change the branch name.

Troubleshoot as a GitLab server admin

Troubleshooting the GitLab Container Registry, most of the times, requires administration access to the GitLab server.

Read how to troubleshoot the Container Registry.

Unable to change path or transfer a project

If you try to change a project’s path or transfer a project to a new namespace, you may receive one of the following errors:

• “Project cannot be transferred, because tags are present in its container registry.”
• “Namespace cannot be moved because at least one project has tags in container registry.”

This issue occurs when the project has images in the Container Registry. You must delete or move these images before you can change the path or transfer the project.

The following procedure uses these sample project names:

• For the current project: example.gitlab.com/org/build/sample_project/cr:v2.9.1
• For the new project: example.gitlab.com/new_org/build/new_sample_project/cr:v2.9.1

Use your own URLs to complete the following steps:

1. Download the Docker images on your computer:

   docker login example.gitlab.com
   docker pull example.gitlab.com/org/build/sample_project/cr:v2.9.1
   

2. Rename the images to match the new project name:

   docker tag example.gitlab.com/org/build/sample_project/cr:v2.9.1 example.gitlab.com/new_org/build/new_sample_project/cr:v2.9.1
   

3. Delete the images in both projects by using the UI or API. There may be a delay while the images are queued and deleted.
4. Change the path or transfer the project by going to Settings > General and expanding Advanced.

5. Restore the images:

   docker push example.gitlab.com/new_org/build/new_sample_project/cr:v2.9.1
   

Follow this issue for details.