GitLab Registry is a powerful tool for managing and sharing container images within your GitLab project. It allows you to store and share your Docker images, which can be used to deploy your applications in a variety of environments. By default, GitLab Registry only allows you to push and pull images from the library namespace. However, it is possible to add arbitrary paths to the registry, allowing you to organize your images in a more meaningful way for your project.
In this guide, we will walk through the process of adding arbitrary paths to your GitLab Registry. We will cover the following topics:
- Creating a new project in GitLab
- Enabling the GitLab Container Registry
- Creating a new repository in the GitLab Registry
- Pushing a Docker image to the new repository
- Tagging the Docker image with the new repository path
- Pulling the Docker image from the new repository
Creating a new project in GitLab
The first step is to create a new project in GitLab. This can be done by clicking on the "+" button in the top right corner of the GitLab dashboard, and selecting "New project". Give your project a name, and select "Public" or "Private" depending on your needs. Once the project has been created, you will be taken to the project's dashboard.
Enabling the GitLab Container Registry
The next step is to enable the GitLab Container Registry for your project. This can be done by clicking on the "Settings" tab in the project's dashboard, and then selecting "Container Registry" from the menu on the left. Click the "Expand" button to reveal the settings for the container registry. To enable the registry, check the box next to "Enable Container Registry".
Once the registry is enabled, you will see a new section titled "Repository". This is where you will create the new repository for your Docker images. Before we do that, however, we need to create a Docker image to push to the registry.
Creating a new repository in the GitLab Registry
To create a new repository in the GitLab Registry, we will use the GitLab API. The API allows us to create new repositories programmatically, without having to use the GitLab web interface. The API endpoint for creating a new repository is:
POST /api/v4/projects/:id/registry/repositories
Where :id is the ID of the project that you want to create the repository in. You can find the ID of your project by navigating to the project's dashboard, and looking at the URL. The ID is the number that appears after /projects/ in the URL.
To create a new repository, we will use the curl command to make a POST request to the API endpoint. The command will look something like this:
curl --request POST "https://gitlab.com/api/v4/projects/<PROJECT\_ID>/registry/repositories" \
--form "name=my-repository" \
--form "description=My%20custom%20Docker%20repository" \
--form "visibility=public" \
--form "tag_list=docker" \
--header "PRIVATE-TOKEN: <YOUR\_PRIVATE\_TOKEN>"
Replace <PROJECT\_ID> with the ID of your project, and replace <YOUR\_PRIVATE\_TOKEN> with your GitLab personal access token. The personal access token can be generated by navigating to the "Settings" tab in your GitLab profile, and selecting "Access Tokens" from the menu on the left. Give your token a name, and select the "api" scope. The token will be displayed once it has been created.
Once you have run the curl command, you should see a JSON response that looks something like this:
{
"id": 12345,
"name": "my-repository",
"description": "My custom Docker repository",
"visibility": "public",
"tag_list": [
"docker"
],
"path": "my-repository",
"path\_with\_namespace": "username/my-repository",
"created\_at": "2021-01-01T00:00:00Z",
"updated\_at": "2021-01-01T00:00:00Z"
}
This means that you have successfully created a new repository in the GitLab Registry. The id field is the ID of the repository, which we will need later to push a Docker image to the repository. The path field is the path to the repository, and the path\_with\_namespace field is the path to the repository with the project namespace included. In this example, the namespace is "username", but it will be different for your project.
Pushing a Docker image to the new repository
Now that we have created a new repository in the GitLab Registry, we can push a Docker image to it. This can be done using the docker command line tool. First, we need to login to the GitLab Registry using the docker login command. The command will look something like this:
docker login registry.gitlab.com
You will be prompted to enter your GitLab username and password. Once you have logged in, you can push a Docker image to the repository using the docker push command. The command will look something like this:
docker push registry.gitlab.com/<PROJECT\_NAMESPACE>/<REPOSITORY\_PATH>:<TAG>
Replace <PROJECT\_NAMESPACE> with the namespace of your GitLab project, <REPOSITORY\_PATH> with the path to the repository that you created earlier, and <TAG> with the tag that you want to give to the Docker image. For example, the command to push a Docker image with the tag "latest" to the repository "my-repository" in the project "my-project" would look like this:
docker push registry.gitlab.com/my-project/my-repository:latest
Once you have run the docker push command, you should see a message indicating that the Docker image has been pushed to the GitLab Registry. The Docker image is now available in the new repository that you created.
Tagging the Docker image with the new repository path
If you want to tag the Docker image with the new repository path, you can use the docker tag command. The command will look something like this:
docker tag <IMAGE\_ID> registry.gitlab.com/<PROJECT\_NAMESPACE>/<REPOSITORY\_PATH>:<TAG>
Replace <IMAGE\_ID> with the ID of the Docker image that you want to tag, <PROJECT\_NAMESPACE> with the namespace of your GitLab project, <REPOSITORY\_PATH> with the path to the repository that you created earlier, and <TAG> with the tag that you want to give to the Docker image. For example, the command to tag a Docker image with the ID "abc123" with the tag "my-tag" in the repository "my-repository" in the project "my-project" would look like this:
docker tag abc123 registry.gitlab.com/my-project/my-repository:my-tag
Once you have run the docker tag command, you can verify that the Docker image has been tagged with the new repository path by running the docker images command. You should see the new tag in the list of Docker images.
Pulling the Docker image from the new repository
Finally, you can pull the Docker image from the new repository using the docker pull command. The command will look something like this:
docker pull registry.gitlab.com/<PROJECT\_NAMESPACE>/<REPOSITORY\_PATH>:<TAG>
Replace <PROJECT\_NAMESPACE> with the namespace of your GitLab project, <REPOSITORY\_PATH> with the path to the repository that you created earlier, and <TAG> with the tag that you want to pull. For example, the command to pull a Docker image with the tag "my-tag" from the repository "my-repository" in the project "my-project" would look like this:
docker pull registry.gitlab.com/my-project/my-repository:my-tag
Once you have run the docker pull command, you should see a message indicating that the Docker image has been pulled from the GitLab Registry. The Docker image is now available on your local machine, and can be run using the docker run command.
In this guide, we have covered the process of adding arbitrary paths to the GitLab Registry. We have learned how to create a new project in GitLab, enable the GitLab Container Registry, create a new repository in the GitLab Registry, push a Docker image to the new repository, tag the Docker image with the new repository path, and pull the Docker image from the new repository. With this knowledge, you can now organize your Docker images in a more meaningful way for your project, and share them with your team or the world.
References
| Title | URL |
|---|---|
| GitLab Container Registry | https://docs.gitlab.com/ee/user/packages/container_registry/ |
| GitLab API: Create a new repository | https://docs.gitlab.com/ee/api/repositories.html#create-a-repository |
| Docker login | https://docs.docker.com/engine/reference/commandline/login/ |
| Docker push | https://docs.docker.com/engine/reference/commandline/push/ |
| Docker tag | https://docs.docker.com/engine/reference/commandline/tag/ |
| Docker pull | https://docs.docker.com/engine/reference/commandline/pull/ |