Registry Cleanup Policies

GitLab Container Registry storage grows relentlessly. Every pipeline that pushes an image adds storage, and without cleanup, costs spiral quickly. Consider a moderately active project: if you push a 500MB image on every commit across 20 commits a day, that's 10GB of storage added daily — 300GB per month — most of which is never pulled again. Multiplied across an organization's projects, the cost becomes enormous.

But cleanup isn't just about cost. It's also about performance (registry operations slow as the registry grows), compliance (regulations require data retention limits), security (old images with known vulnerabilities persist and could be pulled accidentally), and clarity (a clean registry is easier to audit). For all these reasons, automatic cleanup is essential in any serious GitLab deployment.

GitLab provides cleanup policies that automatically remove old images based on rules you define. You specify which images are eligible for deletion (by age, by tag pattern, by name regex) and which should always be kept. GitLab then runs the cleanup daily, deleting images that match the deletion criteria and don't match the keep criteria. This is a fire-and-forget mechanism — once configured, you don't need to think about it again.

Cleanup policies operate on tags, not on individual image layers. When you push an image with a tag, that tag becomes a candidate for cleanup. When a tag is deleted by the cleanup policy, all the image layers that are only referenced by that tag are also deleted (via garbage collection). This means storage is reclaimed, not just metadata.

Every cleanup policy has several parameters that determine its behavior. The enabled flag turns the policy on or off. The cadence determines how often it runs (daily, every few days, or monthly). The older_than parameter specifies the age threshold — images older than this will be considered for deletion. The keep_n parameter specifies how many images to keep regardless of age. The name_regex_delete and name_regex_keep parameters define patterns for inclusion and exclusion.

The logic is: an image tag is deleted if it matches name_regex_delete, is older than older_than, is beyond the keep_n most recent tags, AND does not match name_regex_keep. The combination of these conditions gives fine-grained control. Most teams end up with a simple policy: keep release tags forever, keep the last N images per branch, and delete anything older than 30 or 90 days.

Each parameter of a cleanup policy controls a different aspect of its behavior. Understanding each one is important — they interact in subtle ways, and a small change can have a large effect.

Cleanup policies can be configured through the GitLab UI, the API, or Terraform. The UI is the easiest for one-off configuration; the API is essential for automating across many projects; Terraform is best for infrastructure-as-code deployments.

Regardless of method, the process is: enable cleanup, choose a cadence, set an age threshold and keep count, and define name patterns. Then preview the policy — GitLab shows you which images would be deleted, so you can verify before committing. Once satisfied, save and enable the policy, and it will run on its schedule.

The right retention strategy depends on your workflow. Different types of images have different lifecycle needs. A release image should be kept forever; a feature branch image should be cleaned aggressively; a nightly build might be kept for a week.

Segmenting images by tag pattern enables different retention rules for different categories. Use a consistent tagging convention (e.g., release-v1.2.3 for releases, feature-xyz-abc123 for feature branches, nightly-20240101 for nightlies), then write cleanup rules that match each category. This gives you fine-grained control without complexity.

Cleanup policies remove image tags, but they don't immediately free disk space. Deleting a tag marks the underlying blobs as unreferenced; a separate garbage collection process (usually run by the registry administrator) actually deletes them. On GitLab.com, this happens automatically. On self-hosted GitLab, you may need to run garbage collection manually.

Beyond cleanup, storage management includes monitoring usage, identifying large images, and optimizing image sizes. A 2GB image is 4x the cost of a 500MB image and 4x slower to pull. Building smaller images (smaller base images, multi-stage builds, layer optimization) is often more impactful than cleanup alone.

For self-hosted GitLab, storage is on your infrastructure (object storage or filesystem), and you're responsible for its capacity. For GitLab.com, storage is metered and billed — exceeding your plan's limit requires purchasing additional storage or reducing usage through cleanup and optimization.