Enable the Container Registry for your project

Note:
If you cannot find the Container Registry entry under your project's settings,
that means that it is not enabled in your GitLab instance. Ask your administrator
to enable it.

First, ask your system 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.

Go to your project's General settings
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.

Hit Save changes for the changes to take effect. You should now be able
to see the Registry link in the sidebar.

Build and push images

Notes:

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.

If you visit the 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, the you should be
able to login with:

docker login registry.example.com

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:

Troubleshooting the GitLab Container Registry

Basic Troubleshooting

Check to make sure that the system clock on your Docker client and GitLab server have
been synchronized (e.g. via NTP).

If you are using an S3-backed Registry, double check that the IAM
permissions and the S3 credentials (including region) are correct. See the
sample IAM policy
for more details.

Check the Registry logs (e.g. /var/log/gitlab/registry/current) and the GitLab production logs
for errors (e.g. /var/log/gitlab/gitlab-rails/production.log). You may be able to find clues
there.

Advanced Troubleshooting

NOTE: The following section is only recommended for experts.

Sometimes it's not obvious what is wrong, and you may need to dive deeper into
the communication between the Docker client and the Registry to find out
what's wrong. We will use a concrete example in the past to illustrate how to
diagnose a problem with the S3 setup.

Unexpected 403 error during push

A user attempted to enable an S3-backed Registry. The docker login step went
fine. However, when pushing an image, the output showed:

This error is ambiguous, as it's not clear whether the 403 is coming from the
GitLab Rails application, the Docker Registry, or something else. In this
case, since we know that since the login succeeded, we probably need to look
at the communication between the client and the Registry.

The REST API between the Docker client and Registry is described
here. Normally, one would just
use Wireshark or tcpdump to capture the traffic and see where things went
wrong. However, since all communication between Docker clients and servers
are done over HTTPS, it's a bit difficult to decrypt the traffic quickly even
if you know the private key. What can we do instead?

One way would be to disable HTTPS by setting up an insecure
Registry. This could introduce a
security hole and is only recommended for local testing. If you have a
production system and can't or don't want to do this, there is another way:
use mitmproxy, which stands for Man-in-the-Middle Proxy.

mitmproxy

mitmproxy allows you to place a proxy between your
client and server to inspect all traffic. One wrinkle is that your system
needs to trust the mitmproxy SSL certificates for this to work.

The following installation instructions assume you are running Ubuntu:

If everything is setup correctly, you will see information on the mitmproxy window and
no errors from the curl commands.

Running the Docker daemon with a proxy

For Docker to connect through a proxy, you must start the Docker daemon with the
proper environment variables. The easiest way is to shutdown Docker (e.g. sudo initctl stop docker)
and then run Docker by hand. As root, run: