Introducing GitLab Container Registry

Mark Pundsack ·
May 23, 2016 · 7 min read

Yesterday we released GitLab 8.8, super powering GitLab's built-in continuous integration. With it, you can build a pipeline in GitLab, visualizing your builds, tests, deploys and any other stage of the life cycle of your software. Today (and already in GitLab 8.8), we're releasing the next step: GitLab Container Registry.

What is GitLab Container Registry?

GitLab Container Registry is a secure and private registry for Docker images. Built on open source software, GitLab Container Registry isn't just a standalone registry; it's completely integrated with GitLab.

GitLab is all about having a single, integrated experience and our registry is no exception. You can now easily use your images for GitLab CI, create images specific for tags or branches and much more.

Our container registry is the first Docker registry that is fully integrated with Git repository management and comes out of the box with GitLab 8.8. So if you've upgraded, you already have it! This means our integrated Container Registry requires no additional installation. It allows for easy upload and download of images from GitLab CI. And it's free.

Read the administration documentation to learn how to enable it on your GitLab instance. (This documentation covers everything from self-signed certificates to environment variables, garbage collect commands, various APIs, curl commands, setting rate limits, how to use an external registry, and more.)

Some Docker basics

The main component of a Docker-based workflow is an image, which contains everything needed to run an application. Images are often created automatically as part of continuous integration, so they are updated whenever code changes. When images are built to be shared between developers and machines, they need to be stored somewhere, and that's where a container registry comes in.

The registry is the place to store (or host) and tag images for later use. Developers may want to maintain their own private registry for private images, or for throw-away images used only in testing. Using GitLab Container Registry means you don't need to set up and administer yet another service, or use a public registry.

Tight integration

GitLab Container Registry is fully-integrated with GitLab making it easy for developers to code, test, and deploy Docker container images using GitLab CI and other Docker-compatible tooling.

How GitLab Container Registry can simplify your workflow

GitLab Container Registry is seamless and secure. Here are some examples of how GitLab Container Registry can simplify your development and deployment workflows:

How to start using GitLab Container Registry

First, ask your system administrator to enable GitLab Container Registry following the administration documentation.

After that, you will be allowed to enable Container Registry for your project.

To start using your brand new Container Registry you first have to login:

docker login

Then you can simply build and push images to GitLab:

docker build -t .
docker push

GitLab also offers simple Container Registry management. Go to your project and click Container Registry. This view will show you all tags in your repository and will allow you to delete them and view details about each tag, such as when it was published and how much storage it consumes.

Read more in the GitLab Container Registry user guide.

Use with GitLab CI

You can use GitLab's integrated CI solution to build, push, and deploy your container images.

Note: This feature requires GitLab Runner 1.2.

Note: To use Docker in Docker images you need to have the privileged flag set up in your Runner's configuration. This is not the case for the shared Runners on for now; we plan to enable this flag next week. For the moment you can use your own Runners.

Here's an example GitLab CI configuration file (.gitlab-ci.yml) which builds an image, runs tests, and if the tests are successful, tags the build and uploads the build to the container registry:

  image: docker:git
  - docker:dind
    - docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN
    - docker build -t .
    - docker run /script/to/run/tests
    - docker push
    - master

Here's a more elaborate example that splits up the tasks into four stages, including two tests that run in parallel. The build is stored in the container registry and used by subsequent stages, downloading the image automatically when needed. Changes to master also get tagged as latest and deployed using an application-specific deploy script:

image: docker:git
- docker:dind

- build
- test
- release
- deploy


  - docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN

  stage: build
    - docker build -t $CONTAINER_TEST_IMAGE .
    - docker push $CONTAINER_TEST_IMAGE

  stage: test
    - docker run $CONTAINER_TEST_IMAGE /script/to/run/tests

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

  stage: release
    - docker pull $CONTAINER_TEST_IMAGE
    - docker push $CONTAINER_RELEASE_IMAGE
    - master

  stage: deploy
    - ./
    - master


GitLab Container Registry is the latest addition to GitLab's integrated set of tools for the software development lifecycle and comes with GitLab 8.8 and up. With GitLab Container Registry, testing and deploying Docker containers has never been easier. GitLab Container Registry is available on-premises in GitLab CE and GitLab EE at no additional cost and installs in the same infrastructure as the rest of your GitLab instance.

Container Registry is enabled on, the pricing is simple (it's completely free), and you can start using it right now!

Note: To use Docker in Docker images you need to have the privileged flag set up in your Runner's configuration. This is not the case for the shared Runners on for now. We plan to enable this flag next week.

Edit this page View source