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?
answer
- keep rules beat remove rules
- one tag name is always spared
- the count is per image
- tags go, layers wait
basics
~20 sThe 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.
solid answer
~40 sA GitLab cleanup policy is a scheduled job that deletes **tags**, evaluated per container repository. It collects all tags, always keeps `latest`, keeps only tags matching `name_regex` (**Remove tags matching**), then excludes tags matching `name_regex_keep` (**Keep tags matching**), orders the rest by creation date, excludes the `keep_n` newest (**Keep the most recent**), excludes anything newer than `older_than` (**Remove tags older than**), skips protected and immutable tags, and deletes what remains. So a tag dies only if no keep rule saves it and both remove rules match. Old tags survive when the keep regex is broad, when `keep_n` is high, or because GitLab.com limits each run's time. Storage drops slowly because deleting a tag frees nothing until garbage collection removes layers no tagged image references, and layers shared with kept images never go.
code
bash · 5 linescurl --fail-with-body --request PUT \
--header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
--header "Content-Type: application/json" \
--data '{"container_expiration_policy_attributes":{"enabled":true,"cadence":"7d","keep_n":5,"older_than":"30d","name_regex":".*","name_regex_keep":"release-.*"}}' \
"https://gitlab.example.com/api/v4/projects/<project_id>"go deeper
Recall the four fields: keep the most recent, keep tags matching, remove tags older than, remove tags matching. Know that latest is always kept.
Walk through the evaluation order and explain that a tag dies only when no keep rule saves it and both remove rules match; keep_n is per image.
Diagnose why tags survive and storage stays flat: wide keep regexes, per-image keep_n, run limits, protection, deduplicated layers and garbage collection that is separate from the policy.
Set retention as policy across many projects: what must be reproducible, what is disposable, and how protection, immutability and age-based cleanup together make that guarantee.
## What a cleanup policy deletes A **cleanup policy** is a scheduled job on a project that removes **tags** from that project's container repositories. It does not delete layers or manifests directly. Removing the tag makes the image untagged; the storage comes back only when **garbage collection** removes what no tagged image references. The policy has five fields in the UI, each with an API name: | UI field | API attribute | Meaning | |---|---|---| | **Run cleanup** | `cadence` | how often: `1d`, `7d`, `14d`, `1month`, `3month` | | **Keep the most recent** | `keep_n` | tags always kept **per image**: 1, 5, 10, 25, 50 or 100 | | **Keep tags matching** | `name_regex_keep` | regex of tags to preserve | | **Remove tags older than** | `older_than` | only tags older than this many days, from `1d` to `1095d` | | **Remove tags matching** | `name_regex` | regex of tags eligible for removal; cannot be blank, `.*` by default | Both regexes use **RE2** syntax and are automatically wrapped in `\A` and `\Z`, so `release-.*` must match the whole tag. ## The evaluation order For each repository the policy: 1. collects all tags; 2. excludes the tag named `latest`, which is always kept; 3. keeps in the list only tags that match `name_regex`; 4. excludes tags that match `name_regex_keep`; 5. excludes tags without a manifest; 6. orders the remaining tags by creation date; 7. excludes the `keep_n` most recent of them; 8. excludes tags newer than `older_than`; 9. excludes **protected** tags and **immutable** tags; 10. deletes whatever is left. Read as rules: **keep rules win**. A tag is deleted only when no keep rule saves it and it matches **both** remove rules. Note that `keep_n` counts only tags still in the list after the keep regex, so `latest` and regex-kept tags do not use up its slots. A worked case, with **Keep the most recent** 1, **Keep tags matching** `release-.*`, **Remove tags older than** 14 days and **Remove tags matching** `.*`: | Tag | Age | Outcome | Reason | |---|---|---|---| | `latest` | 30 days | kept | always kept | | `release-1.2` | 40 days | kept | matches the keep regex | | `main-a` | 1 day | kept | newest remaining tag, and younger than 14 days | | `main-b` | 20 days | deleted | not kept, older than 14 days, matches `.*` | | `main-c` | 25 days | deleted | same | ## Why old tags survive - **The keep regex is wider than intended.** `.*-main` or `v.*` can match far more tags than planned. - **`keep_n` is per image name.** A project with ten image repositories and **Keep the most recent** 25 can keep up to 250 tags through that rule alone. - **Protection.** Protected and immutable tags are never deleted by a policy. - **Run limits.** On GitLab.com each run has a limited execution time, so a large backlog takes several runs. On GitLab Self-Managed, administrators bound the work with settings such as `container_registry_cleanup_tags_service_max_list_size` (200 tags per execution by default) and `container_registry_expiration_policies_worker_capacity` (4 workers by default; `0` stops all policies). - **Schedule resets.** Editing and saving the policy resets its interval. - **No images, no policy.** Enabled policies are switched off automatically for projects that have no container image. ## Why storage drops slowly - **Layers are deduplicated** at the root namespace: a layer shared with any kept image still counts and is never freed. - **Garbage collection is separate.** On GitLab.com, and on GitLab Self-Managed registries that use the metadata database, an online collector schedules unreferenced layers and untagged manifests for deletion after 24 hours. On a Self-Managed registry still on legacy metadata storage, deleting tags only marks data as eligible; an administrator runs garbage collection, using the `-m` switch to remove untagged manifests and the layers only they referenced. - **Delayed measurement.** For very large namespaces GitLab falls back to a delayed usage figure that includes untagged layers, so the number moves only after garbage collection. ## Designing a policy that keeps what you need 1. Keep release tags by regex (`release-.*` or a semantic-version pattern), and protect the ones that must never change with tag protection or immutability rules. 2. Remove by age with a high `older_than` first, then lower it once you have watched the background workers. 3. Start with a narrow `name_regex` and widen toward `.*` gradually, as the documentation recommends. 4. Choose `keep_n` per image, remembering it multiplies by the number of repositories. 5. Never rely on `latest` for deployments; the policy keeps it, but nothing pins what it points at.
- In GitLab, does `keep_n` count the `latest` tag or tags saved by **Keep tags matching**?No. The policy removes `latest` and the keep-regex matches from the candidate list before ordering by date, so **Keep the most recent** applies to what is left. With `keep_n` 1, the newest remaining candidate per image survives in addition to `latest` and every regex-kept tag.
- In GitLab Self-Managed, the policy deleted thousands of tags but the storage graph did not move. What is missing?Usually garbage collection. On a registry still using legacy metadata storage, deleting tags only marks images as eligible; an administrator must run registry garbage collection, with `-m` to remove untagged manifests and their unreferenced layers. Registries on the metadata database, like GitLab.com's, collect unreferenced data online about 24 hours later. Layers shared with kept tags are never freed.
- A tag matching Remove tags older than is deleted even if it matches Keep tags matching.
- keep_n is counted across the whole project, not per image.
- The cleanup policy deletes the image layers in the same run.
- latest is deleted like any other tag once it is old enough.
- Protected or immutable tags are removed if they match the remove regex.