Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 36 ยท Packages and Registry

GitLab Container Registry

Build and push Docker images to the GitLab Container Registry from CI, use predefined variables for login, tag images well, set cleanup policies and use the dependency proxy.

When a pipeline builds a container image, the image needs a home. Pushing it to a public service works, but then your build depends on another account, other credentials and another bill. GitLab includes a Container Registry for every project: a private image store that uses the same permissions, tokens and pipelines as your code.

This lesson shows image naming, logging in from CI, building and pushing, tagging strategy, pulling in deployment, cleanup policies and the dependency proxy. Docker and a registry cannot run on this site, so the commands are read-only; the examples model tag rules and cleanup. For Docker itself, see the Docker tutorial on this site at /docker.

Where the registry lives

Every project has a registry path derived from its address. On GitLab.com a project at gitlab.com/acme/shop stores images under registry.gitlab.com/acme/shop, and you can add sub-names: registry.gitlab.com/acme/shop/api:1.4.0. On a self-managed server the registry host is set by the administrator and is often registry.example.com. You see the list of repositories and tags in the project menu under Deploy > Container Registry (the position of the menu entry differs between versions).

Inside a pipeline you never type the address; predefined variables hold it:

Variable Value
CI_REGISTRY The registry host, for example registry.gitlab.com
CI_REGISTRY_IMAGE The full path of the project's registry, without a tag
CI_REGISTRY_USER A user name for login inside the job
CI_REGISTRY_PASSWORD A short-lived password for this job (it is the job token)
CI_COMMIT_SHA, CI_COMMIT_SHORT_SHA, CI_COMMIT_REF_SLUG, CI_COMMIT_TAG Good ingredients for tags

Building and pushing with Docker-in-Docker

The classic approach runs a Docker daemon as a service next to the job. The runner must allow privileged containers for this to work, which is a security decision (ask your administrator about the runner policy; scanning images is covered in Security Scanning).

YAML
build_image:
  stage: build
  image: docker:27
  services:
    - docker:27-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  before_script:
    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
  script:
    - docker build --pull -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA" .
    - docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA"
  rules:
    - if: $CI_COMMIT_BRANCH

Passing the password with --password-stdin keeps it out of the process list. Use the version tags that match your runner and your own choices; the 27 above is an example.

Docker-in-Docker is not the only way. Privileged mode gives a job wide access to the host, so many teams prefer daemonless builders such as Buildah, or BuildKit in rootless mode, and a runner that mounts the host Docker socket is a sharper risk still. Pick the approach your platform team has approved. The login and tag conventions below stay the same whichever builder you use.

A tagging strategy

Tags are labels pointing to an image. A useful scheme gives each tag one job:

  • :<commit-sha>: immutable, unique to one commit. Deployments should use this.
  • :<branch-slug> such as :main: moving, always the latest build of a branch. Handy for "what is on main right now".
  • :1.4.0, :1.4, :1: release tags created from Git tags. Users can follow a major or minor line.
  • :latest: avoid for deployments; it hides which version is running.

Build once and re-tag instead of rebuilding: the image that was tested is exactly the image you deploy. Promote it by adding a tag (for example with docker tag and docker push, or a registry copy tool), not by building again from the source.

flowchart LR
  C["commit abc123"] --> B["build job"]
  B --> I["image :abc123"]
  I --> T["tests and scans"]
  T --> M[":main (moving tag)"]
  T --> R[":1.4.0 on Git tag"]
  R --> D["deploy by tag or digest"]

One build, several tags: the content stays the same, only the labels change.

Pulling in deployments

Servers and clusters need permission to pull private images. Create a deploy token with the read_registry scope (Settings > Repository > Deploy tokens), or use a project access token with a Reporter role and read_registry. Store the credentials in the cluster as an image pull secret; do not reuse your personal token. Deploy tokens carry an expiry date option, so use it.

Cleanup policies

Every pipeline can push an image, so registries grow fast. A cleanup policy (Settings > Packages and registries > Container Registry) removes tags automatically. You set:

  • how often it runs,
  • how many tags to keep per image (for example the newest 10),
  • the age after which tags are removed (for example older than 30 days),
  • a regular expression for tags to keep always (^v\d+\.\d+\.\d+$ for releases),
  • a regular expression for tags to remove.

Without cleanup, storage costs climb quietly. Deleting a tag does not free the layers until garbage collection runs on a self-managed server; GitLab.com handles that for you.

The dependency proxy

Public registries rate-limit anonymous pulls, and a busy CI system may reach the limit. The dependency proxy is a pull-through cache in a group: you pull gitlab.com/acme/dependency_proxy/containers/node:22 instead of node:22, GitLab fetches and caches the image once, and later pulls come from the cache. Using the variable CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX in image: keeps the address portable:

YAML
default:
  image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/node:22

Stand-in: tag names and a cleanup policy

The first example builds the list of tags for a pipeline from the variable values, using the scheme above.

JS Which tags does this pipeline push?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second example simulates a cleanup policy: keep the newest N tags, always keep tags matching a pattern, and remove older tags that match the removal pattern.

JS A cleanup policy

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which variable holds the full registry path of the current project, without a tag?

    CI_REGISTRY is only the host. CI_REGISTRY_IMAGE is the project's repository path, to which you append :tag.
  2. 2. Why tag deployed images with the commit SHA rather than latest?

    latest moves with each build and hides the version. A commit-based tag points to one build forever.
  3. 3. Why use docker login with --password-stdin?

    Passing the password as an argument can expose it to other processes; reading it from standard input avoids that.
  4. 4. What does the dependency proxy solve?

    It is a pull-through cache: the first pull fetches the image, later pulls come from GitLab.
  5. 5. What should a server use to pull private images with read-only access?

    A deploy token has a narrow scope and can expire, so a leak does less damage than a personal token would.

Summary

  • Each project gets a private registry at a path built from its address; the predefined CI_REGISTRY* variables hold what a job needs.
  • Build once, tag by commit SHA, add moving and release tags, and deploy by immutable tag.
  • Use deploy tokens for pulls; set cleanup policies so storage does not grow forever.
  • The dependency proxy caches public images for your group.

Next: Package Registry