skip to content

Registries and Packages

GitLab ships the registries alongside the code: a Container Registry your pipeline pushes images to, a Package Registry for npm, Maven, PyPI and Helm, and a Dependency Proxy that caches upstream pulls. Interviewers ask because keeping artifacts next to the pipeline that built them simplifies auth and traceability.

on this pageshow

questions

6

In GitLab, when a CI/CD job pushes an image to its project's container registry, which predefined variables supply the address and the credentials?

level: juniorimportance: must knowfreq 50%

answer

  1. host, namespace, project, optional path
  2. one variable is the host, one the path
  3. a password that dies with the job
  4. same value as the job token

basics

~10 s

CI_REGISTRY is the registry host, CI_REGISTRY_IMAGE is the project's image path under it, and CI_REGISTRY_USER with CI_REGISTRY_PASSWORD log the job in; that password equals CI_JOB_TOKEN and is valid only while the job runs.

solid answer

~40 s

Every GitLab project gets a container registry whose image names follow `<registry host>/<namespace>/<project>[/<optional path>]`, with at most two extra levels. In a job, `CI_REGISTRY` is the host (with port, if any) and `CI_REGISTRY_IMAGE` is the project's base path, so you tag `$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA` or `$CI_REGISTRY_IMAGE/api:...`. You log in with `echo "$CI_REGISTRY_PASSWORD" | docker login "$CI_REGISTRY" -u "$CI_REGISTRY_USER" --password-stdin`; that password is the job token's value, so `CI_JOB_TOKEN` with the user `gitlab-ci-token` works too. It carries the access of the user who triggered the pipeline and expires when the job ends, which is right for the pipeline and wrong for anything that pulls later, such as a cluster. The registry variables exist only when the container registry is enabled.

code

bash · 4 lines
bash
# inside a job that already has a Docker client and a local image named app
echo "$CI_REGISTRY_PASSWORD" | docker login "$CI_REGISTRY" -u "$CI_REGISTRY_USER" --password-stdin
docker tag app "$CI_REGISTRY_IMAGE/api:$CI_COMMIT_SHORT_SHA"
docker push "$CI_REGISTRY_IMAGE/api:$CI_COMMIT_SHORT_SHA"

go deeper

for a junior

Recall the four variables and what each holds: host, project image path, per-job user and per-job password. Be able to write the login, tag and push lines from memory.

for a middle

Explain the naming rule with its two extra levels, why the password equals the job token, and what the job token can reach. Mention the short registry JWT and the large-push failure it causes.

for a senior

Show where the job credential stops being the right one: cross-project pushes behind an allowlist, consumers that pull after the job ends, project renames that move every path. Pick the long-lived credential deliberately.

for a principal

Frame registry naming as an organisational contract: image paths inherit the group structure, so a regrouping moves every image reference. Weigh that against the auth and traceability gained by keeping images beside the code.

## What the registry is and where an image lives GitLab ships a **container registry** with every project (an administrator enables it for a GitLab Self-Managed instance; on GitLab.com it is on). A container registry is a server that stores container images, and GitLab ties each stored image to the project that owns it. The tie is the **name**: an image's path must start with the project's own path. The naming convention is: `<registry server>/<namespace>/<project>[/<optional path>]` You may append **up to two levels** after the project path. For a project `acme/shop` on `registry.example.com`: | Image reference | Valid? | Why | |---|---|---| | `registry.example.com/acme/shop:1.4.2` | Yes | the project path itself | | `registry.example.com/acme/shop/api:1.4.2` | Yes | one extra level | | `registry.example.com/acme/shop/api/worker:rc1` | Yes | two extra levels | | `registry.example.com/acme/shop/a/b/c:1` | No | three extra levels | | `registry.example.com/acme/api:1.4.2` | No | not under the project path | Because the path always matches the project, you cannot rename or move only the registry; renaming or transferring the project is what changes it. ## The predefined registry variables GitLab injects these into every job when the registry is enabled: | Variable | Holds | Example | |---|---|---| | `CI_REGISTRY` | the registry server, `<host>[:<port>]` | `registry.example.com` | | `CI_REGISTRY_IMAGE` | the project's base image path | `registry.example.com/acme/shop` | | `CI_REGISTRY_USER` | a per-job user for the project's registry | set by GitLab | | `CI_REGISTRY_PASSWORD` | that user's password, equal to `CI_JOB_TOKEN` | set by GitLab | Key points: - `CI_REGISTRY` is only the **host**; `CI_REGISTRY_IMAGE` already contains the namespace and project, so you never assemble the path by hand. - `CI_REGISTRY_USER` and `CI_REGISTRY_PASSWORD` are **job-only** variables: they exist while the job runs. - `CI_REGISTRY_IMAGE` is available only if the registry is enabled for the project; if a project owner turned the registry off, the variable is missing and the push fails. ## Logging in and pushing from a job The usual sequence inside a job that already has a Docker client and a built image: 1. Pipe the password into `docker login "$CI_REGISTRY" -u "$CI_REGISTRY_USER" --password-stdin`. 2. Tag the image under `$CI_REGISTRY_IMAGE`, usually with something unique such as `$CI_COMMIT_SHORT_SHA`. 3. Push the tag. Two equivalent logins use the job token directly: `-u "$CI_REGISTRY_USER"` with `CI_JOB_TOKEN` as the password, or the fixed user name `gitlab-ci-token` with `CI_JOB_TOKEN`. Use `--password-stdin` instead of `-p`, so the secret never appears on a command line. How the job gets the image into the job (Docker-in-Docker, a daemonless builder) is a runner and executor question; the registry only cares about the login, the name and the push. ## What the job credential can and cannot do The **CI/CD job token** gets the access of the user who triggered the pipeline, limited to the resources the job token is allowed to reach. For the registry that means: - read (pull) and write (push) on the registry of the **project that runs the job**; - another project's registry only when that project lets this one in through its job token allowlist (or, for some read access, when the other project is public or internal); - nothing once the job ends, because the token is valid only while the job is running. That last point decides when the job token is the wrong tool. A cluster pulling at deploy time, a server or a developer laptop pulls long after the job finished, so they need a **long-lived** credential: a deploy token with the right registry scope, not a copied job password and not someone's personal access token. ## How authentication actually works underneath `docker login` sends the credentials to the registry, which sends the client to GitLab to validate them. GitLab then issues short-lived **JWTs**, each authorised for one operation. Those expire after **5 minutes by default on GitLab Self-Managed** (an administrator can raise the **Authorization token duration (minutes)**) and after **15 minutes on GitLab.com**. A very large push that outlives its token fails with `unauthorized: authentication required`, which looks like a credentials problem but is a duration problem. ## Common mistakes - Pushing to `registry.example.com/acme/api` from project `acme/shop` and getting denied: the name is outside the project's path. - Hard-coding a personal access token as a CI/CD variable to push to the job's own registry, when the predefined credentials already do it and expire on their own. - Copying `CI_REGISTRY_PASSWORD` into a deployment target: it stops working when the job ends. - Using a password login from an account with two-factor authentication; a token is required instead. - Building straight to `latest` from several jobs, so concurrent pipelines overwrite each other; a commit-based tag is unique per job.

  • In GitLab, why can a large image push fail halfway with `unauthorized: authentication required` although the login worked?
    After `docker login`, the registry works with short-lived JWTs issued by GitLab. They last 5 minutes by default on GitLab Self-Managed and 15 minutes on GitLab.com. If the upload of big layers outlives the token, the push is rejected mid-way. On Self-Managed an administrator can raise **Authorization token duration (minutes)**; otherwise make the image smaller or the link faster.
  • In GitLab, can a job push to a different project's container registry with `CI_JOB_TOKEN`?
    Only when the target project allows it: the job's project or group must be on the target project's job token allowlist, and the user who triggered the pipeline needs a role in the target that permits pushing, since the job token inherits that user's access. Without both, use a credential issued for the target project, such as its deploy token with `read_registry` and `write_registry`.
  • In GitLab, what happens to the image paths when you rename or transfer a project that has container images?
    The registry path always follows the project path, so it moves with the project; you cannot rename the registry on its own. GitLab limits renames of projects with populated container repositories to projects with up to 1,000 of them, and on GitLab Self-Managed the documented route is to delete the images before moving or renaming. Every consumer then needs the new path.

  • CI_REGISTRY_IMAGE is just the host, so you append group and project yourself.
  • CI_REGISTRY_PASSWORD is a long-lived secret you can hand to a cluster.
  • A job needs a personal access token to push to its own project's registry.
  • Any image name under the registry host is accepted, whatever the project path.
  • Passing the password with -p is as safe as --password-stdin.
open as a page

In GitLab, how does the dependency proxy stop CI jobs from hitting Docker Hub pull rate limits, and what changes in each job's image reference?

level: middleimportance: should knowfreq 36%

basics

~10 s

The group-level dependency proxy caches Docker Hub manifests and blobs and checks freshness with uncounted HEAD requests. Jobs prefix images with CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX (or the DIRECT variant), and the runner signs in automatically.

open as a page

In GitLab, which deploy token scopes does a production cluster need to pull a project's images, and why not reuse CI_JOB_TOKEN or a personal token?

level: middleimportance: should knowfreq 32%

basics

~20 s

A deploy token with read_registry is enough to pull; pushing needs read_registry and write_registry, and packages use read_package_registry. The job token dies with its job and a personal token is tied to one person, so neither suits a long-lived consumer.

open as a page

In GitLab's package registry, why must npm, Maven and PyPI packages publish to a project, even when consumers install from group or instance endpoints?

level: middleimportance: should knowfreq 28%

basics

~20 s

Every package is stored in, and permissioned by, one project, so npm, Maven and PyPI publish only to the project endpoint. Group and instance endpoints are read views that aggregate those projects, with naming rules for the instance level.

open as a page

In GitLab, a container registry cleanup policy is on, yet old tags survive and storage barely drops; how do keep_n, older_than, name_regex and name_regex_keep decide what gets deleted?

level: seniorimportance: should knowfreq 20%

basics

~20 s

The policy starts from every tag, spares latest, keeps only name_regex matches, drops name_regex_keep matches, spares the keep_n newest, spares tags younger than older_than, skips protected and immutable tags, and deletes the rest; layers go later, by garbage collection.

open as a page

In GitLab 19.4, a pipeline run by a Maintainer overwrote the release image tag v2.3.0; would protected or immutable container tags have prevented it, and how?

level: seniorimportance: nice to knowfreq 12%

basics

~20 s

A protected tag rule stops it only if its minimum push role is above Maintainer; an immutable tag rule (Ultimate, generally available since GitLab 18.10) stops anyone from overwriting or deleting an existing matching tag.

open as a page