Professional Documents
Culture Documents
html
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/ .
If you cannot find the Packages > 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:
For more information on running Docker containers, visit the Docker documentation .
1 of 7 21-Feb-20, 4:57 PM
GitLab Container Registry | GitLab https://docs.gitlab.com/ee/user/packages/container_registry/index.html
If a project is private, credentials will need to be provided for authorization. There are two ways to do this:
GitLab supports up to three levels of image repository names. The following examples of image tags are valid:
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.
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
2 of 7 21-Feb-20, 4:57 PM
GitLab Container Registry | GitLab https://docs.gitlab.com/ee/user/packages/container_registry/index.html
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:
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 .
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:
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
3 of 7 21-Feb-20, 4:57 PM
GitLab Container Registry | GitLab https://docs.gitlab.com/ee/user/packages/container_registry/index.html
4 of 7 21-Feb-20, 4:57 PM
GitLab Container Registry | GitLab https://docs.gitlab.com/ee/user/packages/container_registry/index.html
If you forget to set the service alias, the docker:19.03.1 image won’t find the dind service, and an error like the following will be
thrown:
Expiration policy
Introduced in GitLab 12.8.
It is possible to create a per-project expiration policy, so that you can make sure that older tags and images are regularly removed
from the Container Registry.
The expiration 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:
Select all tags, keep at least 1 tag per image, expire any tag older than 14 days, run once a month, and the policy is enabled:
Select only tags with a name that contains stable , keep at least 50 tag per image, expire any tag older than 7 days, run every
day, and the policy is enabled:
5 of 7 21-Feb-20, 4:57 PM
GitLab Container Registry | GitLab https://docs.gitlab.com/ee/user/packages/container_registry/index.html
Limitations
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.
Leading underscore
6 of 7 21-Feb-20, 4:57 PM
GitLab Container Registry | GitLab https://docs.gitlab.com/ee/user/packages/container_registry/index.html
Trailing hyphen/dash
To get around this, you can change the group path, change the project path or change the branch name.
If you spot an error or a need for improvement and would like to fix it yourself in a
merge request
7 of 7 21-Feb-20, 4:57 PM