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?
answer
- not tied to a person
- read for pull, read plus write for push
- package registry has its own scopes
- a token name that becomes CI variables
basics
~20 sA 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.
solid answer
~40 sA GitLab **deploy token** is a username and token pair created on a project or a group, not on a user. For a cluster that only pulls, give it `read_registry`; a pusher needs both `read_registry` and `write_registry`; package consumers use `read_package_registry` (and `write_package_registry` to publish). `CI_JOB_TOKEN` is valid only while its job runs, so a cluster pulling an hour later would fail, and a personal access token carries one person's access, often far more than registry reads, and breaks when that person leaves. A group deploy token covers every project in the group, which suits a cluster pulling from several projects. Deploy tokens do not expire unless you set a date, so rotation is your job, and they cannot push to protected container repositories or protected packages.
code
bash · 3 lines# on a host outside GitLab, using a project deploy token that has only read_registry
echo "$DEPLOY_TOKEN" | docker login registry.example.com -u gitlab+deploy-token-7 --password-stdin
docker pull registry.example.com/acme/shop/api:1.4.2go deeper
Remember that deploy tokens belong to a project or group, not a person, and the three registry scopes: read_registry to pull, read plus write to push, read_package_registry for packages.
Explain why the job token and personal tokens fail a long-lived consumer, how gitlab-deploy-token becomes CI_DEPLOY_USER and CI_DEPLOY_PASSWORD, and the immediate-child rule for group tokens.
Choose project against group tokens by blast radius, give each consumer the narrowest scope, set expiry dates, and know that protected repositories and packages refuse deploy-token pushes.
Treat deploy tokens as an inventory of non-human credentials: who owns each, what it reaches, when it expires. The trade-off is convenience of one group token against isolation of many project tokens.
## What a deploy token is A **deploy token** is a credential that belongs to a project or a group rather than to a person. It is a pair: - a **username**, by default in the form `gitlab+deploy-token-{n}`, or a custom name you choose; - a **token**, used as the password in HTTP authentication. It works for Git over HTTPS, for the container registry and for the package registry endpoints (paths containing `packages/<format>`). It does **not** work for SSH, and it cannot call the general GitLab API outside those package endpoints. You see the token value once, when you create it. Who can create one: - a **project deploy token**: Maintainer or Owner of the project; permissions apply to that project only; - a **group deploy token**: Owner of the group; permissions apply to all projects in the group. ## The scopes | Scope | Grants | |---|---| | `read_repository` | `git clone` of the repository | | `read_registry` | pull images from the project's container registry | | `write_registry` | push images; pushing needs `read_registry` as well | | `read_package_registry` | read packages from the project's package registry | | `write_package_registry` | publish packages to the project's package registry | For the scenario in the question: 1. A cluster that only runs images needs `read_registry` and nothing else. 2. An outside build system that publishes images needs `read_registry` **and** `write_registry`; `write_registry` alone is not enough. 3. A consumer that installs internal npm or Maven packages needs `read_package_registry`. Keep each token to the smallest set of scopes its consumer uses, so a leaked token exposes as little as possible. ## Why not the job token or a personal token | Credential | Lifetime | Tied to | Problem for a cluster | |---|---|---|---| | `CI_JOB_TOKEN` / `CI_REGISTRY_PASSWORD` | until the job ends | the triggering user's access | stops working minutes after the pipeline | | Personal access token | until it expires or is revoked | one person | breaks when they leave; usually wider than registry reads | | Deploy token | no expiry unless you set one | the project or group | must be rotated deliberately | The job token is built for the pipeline itself. A cluster pulls at deploy time, at reschedule time and at scale-out time, long after any job ended. A personal access token works, but it couples production to one employee's account, and the scope needed for many package formats is broad. The deploy token's whole point is that the credential outlives people and pipelines while carrying only the access you gave it. ## The special `gitlab-deploy-token` If you name a deploy token exactly `gitlab-deploy-token`, GitLab exposes it to the project's CI/CD jobs as: - `CI_DEPLOY_USER` — the username; - `CI_DEPLOY_PASSWORD` — the token. A job can then log in with `echo "$CI_DEPLOY_PASSWORD" | docker login "$CI_REGISTRY" -u "$CI_DEPLOY_USER" --password-stdin`, which is how a pipeline hands a long-lived pull credential to the environment it deploys to. When `gitlab-deploy-token` is defined on a **group**, the variables reach only the group's **immediate child projects**, not projects in deeper subgroups. ## Limits and hardening - **No expiry by default.** You can set an expiry date; it takes effect at 00:00 UTC on that date. Without one, rotation is a manual task, so record where each token is used. - **Protected container repositories reject deploy tokens.** A deploy token cannot push to a container repository matched by a protection rule, whatever its scopes; it works only with unprotected repositories. - **Protected packages reject deploy tokens.** A package matched by a package protection rule cannot be pushed with a deploy token. - **External authorization** on an instance disables deploy tokens for Git and package registry operations. - **Runner hygiene matters.** GitLab deploy tokens are long-lived and therefore attractive to steal; the documentation warns against reusing machines with Docker `privileged` mode or sharing a host through the `shell` executor. ## Putting it together for a cluster 1. Create a **group** deploy token if the cluster pulls from several projects in one group, or a project token if it pulls from one. 2. Give it only `read_registry`. 3. Store it in the cluster as a registry credential for the registry host. 4. Set an expiry date and a reminder to rotate it, and revoke it when the cluster is retired.
- In GitLab, what is special about a deploy token named `gitlab-deploy-token`?GitLab exposes it to CI/CD jobs as `CI_DEPLOY_USER` and `CI_DEPLOY_PASSWORD`, so a pipeline can use or hand on a long-lived registry credential without storing it as a custom variable. Defined on a group, it reaches only the group's immediate child projects.
- In GitLab, can a deploy token with `write_registry` push to a protected container repository?No. Deploy tokens cannot push images to container repositories matched by a protection rule, regardless of their scopes. Pushing there needs a user, or a token acting as one, whose role meets the rule's **Minimum access level for push**. The same applies to protected packages.
- In GitLab, when would you choose a group deploy token over several project deploy tokens?When one consumer, such as a cluster, pulls from many projects in the same group: one group token with `read_registry` covers them all and is one secret to rotate. Project tokens are better when consumers must be isolated, because a leaked group token exposes every project in the group.
- write_registry alone lets a deploy token push images.
- CI_JOB_TOKEN works for a cluster as long as the pipeline succeeded.
- A deploy token stops working when the user who created it leaves.
- Deploy tokens expire after a fixed default period, so rotation is automatic.
- A deploy token with write_registry can push to any protected container repository.