- Enable the Container Registry
- Container Registry domain configuration
- Disable Container Registry site-wide
- Disable Container Registry for new projects site-wide
- Configure storage for the Container Registry
- Change the registry’s internal port
- Disable Container Registry per project
- Use an external container registry with GitLab as an auth endpoint
- Configure Container Registry notifications
- Run the Cleanup policy now
- Container Registry garbage collection
- Configuring GitLab and Registry to run on separate nodes (Omnibus GitLab)
- Architecture of GitLab Container Registry
-
Troubleshooting
- Using self-signed certificates with Container Registry
- Docker login attempt fails with: ‘token signed by untrusted key’
- AWS S3 with the GitLab registry error when pushing large images
- Supporting older Docker clients
- Docker connection error
- Image push errors
- Enable the Registry debug server
- Access old schema v1 Docker images
- Tags with an empty name
- Advanced Troubleshooting
- Missing
gitlab-registry.key
prevents container repository deletion
GitLab Container Registry administration
With the GitLab Container Registry, every project can have its own space to store Docker images.
Read more about the Docker Registry in the Docker documentation.
This document is the administrator’s guide. To learn how to use the GitLab Container Registry, see the user documentation.
Enable the Container Registry
Omnibus GitLab installations
If you installed GitLab by using the Omnibus installation package, the Container Registry may or may not be available by default.
The Container Registry is automatically enabled and available on your GitLab domain, port 5050 if:
- You’re using the built-in Let’s Encrypt integration, and
- You’re using GitLab 12.5 or later.
Otherwise, the Container Registry is not enabled. To enable it:
- You can configure it for your GitLab domain, or
- You can configure it for a different domain.
The Container Registry works under HTTPS by default. You can use HTTP but it’s not recommended and is beyond the scope of this document. Read the insecure Registry documentation if you want to implement this.
Installations from source
If you have installed GitLab from source:
- You must install Registry by yourself.
- After the installation is complete, to enable it, you must configure the Registry’s
settings in
gitlab.yml
. - Use the sample NGINX configuration file from under
lib/support/nginx/registry-ssl
and edit it to match thehost
,port
, and TLS certificate paths.
The contents of gitlab.yml
are:
registry:
enabled: true
host: registry.gitlab.example.com
port: 5005
api_url: http://localhost:5000/
key: config/registry.key
path: shared/registry
issuer: gitlab-issuer
Where:
Parameter | Description |
---|---|
enabled |
true or false . Enables the Registry in GitLab. By default this is false . |
host |
The host URL under which the Registry runs and users can use. |
port |
The port the external Registry domain listens on. |
api_url |
The internal API URL under which the Registry is exposed. It defaults to http://localhost:5000 . Do not change this unless you are setting up an external Docker registry. |
key |
The private key location that is a pair of Registry’s rootcertbundle . Read the token auth configuration documentation. |
path |
This should be the same directory like specified in Registry’s rootdirectory . Read the storage configuration documentation. This path needs to be readable by the GitLab user, the web-server user and the Registry user. Read more in #configure-storage-for-the-container-registry. |
issuer |
This should be the same value as configured in Registry’s issuer . Read the token auth configuration documentation. |
A Registry init file is not shipped with GitLab if you install it from source. Hence, restarting GitLab does not restart the Registry should you modify its settings. Read the upstream documentation on how to achieve that.
At the absolute minimum, make sure your Registry configuration
has container_registry
as the service and https://gitlab.example.com/jwt/auth
as the realm:
auth:
token:
realm: https://gitlab.example.com/jwt/auth
service: container_registry
issuer: gitlab-issuer
rootcertbundle: /root/certs/certbundle
auth
is not set up, users can pull Docker images without authentication.Container Registry domain configuration
There are two ways you can configure the Registry’s external domain. Either:
- Use the existing GitLab domain. The Registry listens on a port and reuses the TLS certificate from GitLab.
- Use a completely separate domain with a new TLS certificate for that domain.
Because the Container Registry requires a TLS certificate, cost may be a factor.
Take this into consideration before configuring the Container Registry for the first time.
Configure Container Registry under an existing GitLab domain
If the Registry is configured to use the existing GitLab domain, you can expose the Registry on a port. This way you can reuse the existing GitLab TLS certificate.
If the GitLab domain is https://gitlab.example.com
and the port to the outside world is 5050
, here is what you need to set
in gitlab.rb
or gitlab.yml
if you are using Omnibus GitLab or installed
GitLab from source respectively.
Ensure you choose a port different than the one that Registry listens to (5000
by default),
otherwise conflicts occur.
registry_external_url
line, rather than the port listed under
gitlab_rails['registry_port']
(default 5000
).Omnibus GitLab installations
-
Your
/etc/gitlab/gitlab.rb
should contain the Registry URL as well as the path to the existing TLS certificate and key used by GitLab:registry_external_url 'https://gitlab.example.com:5050'
The
registry_external_url
is listening on HTTPS under the existing GitLab URL, but on a different port.If your TLS certificate is not in
/etc/gitlab/ssl/gitlab.example.com.crt
and key not in/etc/gitlab/ssl/gitlab.example.com.key
uncomment the lines below:registry_nginx['ssl_certificate'] = "/path/to/certificate.pem" registry_nginx['ssl_certificate_key'] = "/path/to/certificate.key"
-
Save the file and reconfigure GitLab for the changes to take effect.
-
Validate using:
openssl s_client -showcerts -servername gitlab.example.com -connect gitlab.example.com:5050 > cacert.pem
If your certificate provider provides the CA Bundle certificates, append them to the TLS certificate file.
An administrator may want the container registry listening on an arbitrary port such as 5678
.
However, the registry and application server are behind an AWS application load balancer that only
listens on ports 80
and 443
. The administrator may simply remove the port number for
registry_external_url
, so HTTP or HTTPS is assumed. Then, the rules apply that map the load
balancer to the registry from ports 80
or 443
to the arbitrary port. This is important if users
rely on the docker login
example in the container registry. Here’s an example:
registry_external_url 'https://registry-gitlab.example.com'
registry_nginx['redirect_http_to_https'] = true
registry_nginx['listen_port'] = 5678
Installations from source
-
Open
/home/git/gitlab/config/gitlab.yml
, find theregistry
entry and configure it with the following settings:registry: enabled: true host: gitlab.example.com port: 5050
- Save the file and restart GitLab for the changes to take effect.
- Make the relevant changes in NGINX as well (domain, port, TLS certificates path).
Users should now be able to sign in to the Container Registry with their GitLab credentials using:
docker login gitlab.example.com:5050
Configure Container Registry under its own domain
When the Registry is configured to use its own domain, you need a TLS
certificate for that specific domain (for example, registry.example.com
). You might need
a wildcard certificate if hosted under a subdomain of your existing GitLab
domain, for example, registry.gitlab.example.com
.
As well as manually generated SSL certificates (explained here), certificates automatically generated by Let’s Encrypt are also supported in Omnibus installs.
Let’s assume that you want the container Registry to be accessible at
https://registry.gitlab.example.com
.
Omnibus GitLab installations
-
Place your TLS certificate and key in
/etc/gitlab/ssl/registry.gitlab.example.com.crt
and/etc/gitlab/ssl/registry.gitlab.example.com.key
and make sure they have correct permissions:chmod 600 /etc/gitlab/ssl/registry.gitlab.example.com.*
-
After the TLS certificate is in place, edit
/etc/gitlab/gitlab.rb
with:registry_external_url 'https://registry.gitlab.example.com'
The
registry_external_url
is listening on HTTPS. -
Save the file and reconfigure GitLab for the changes to take effect.
If you have a wildcard certificate, you must specify the path to the
certificate in addition to the URL, in this case /etc/gitlab/gitlab.rb
looks like:
registry_nginx['ssl_certificate'] = "/etc/gitlab/ssl/certificate.pem"
registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key"
Installations from source
-
Open
/home/git/gitlab/config/gitlab.yml
, find theregistry
entry and configure it with the following settings:registry: enabled: