skip to content

Retention, Cleanup & Storage

Artifact stores grow forever unless something deletes. Interviewers ask how cleanup policies and registry garbage collection work, and how a delete can remove what a deployment still needs.

on this pageshow

questions

5

What does a cleanup policy in a repository manager such as Nexus Repository or Artifactory do, and which criteria can it select components by?

level: juniorimportance: must knowfreq 62%

answer

  1. a scheduled rule over repositories
  2. age versus last download
  3. release or pre-release
  4. keep the newest N per component
  5. preview before the first run

basics

~20 s

A cleanup policy is a scheduled rule in a repository manager that removes components matching criteria such as age, days since last download, release or pre-release status, a keep-newest-N count and name patterns. Nexus Repository configures none by default.

solid answer

~40 s

A cleanup policy is a rule a repository manager evaluates on a schedule to remove components nobody needs. In Nexus Repository it targets a format and uses criteria such as **component age**, **component usage** (days since last download, or since publishing if never downloaded), **release type**, **retain select versions** (keep the newest N) and an **asset name matcher**; inside one policy the criteria combine, so only components meeting every condition go. Artifactory's retention policies carry a duration in days, a maximum number of versions or tags, package types and include/exclude patterns. Snapshot purging is the classic use: Maven `-SNAPSHOT` versions count as pre-releases. Always read the preview or dry run before the first real run, and remember that in Nexus Repository the run only soft-deletes until a compaction task frees the disk.

go deeper

for a junior

Recall the criteria by name: age, last download, release or pre-release, keep the newest N, and name patterns. Say that nothing is cleaned until someone creates and attaches a policy.

for a middle

Explain that criteria inside a Nexus policy combine, that age means first cache download on a proxy but upload time on a hosted repository, and that a never-downloaded component falls back to its publish date.

for a senior

Show the operational habit: one repository and one format per policy, a preview or dry run read before every first run, and a separate, far longer rule for releases than for snapshots.

for a principal

Frame policies as an organisation's storage contract: which content classes may be deleted, on what evidence, and who signs off when a policy's preview shows it would remove something still in use.

## Why a repository needs a cleanup policy A repository manager keeps everything it is given. CI pipelines publish a new snapshot or pre-release on every merge, proxy repositories cache every version any build ever asked for, and container repositories collect one image per build. Nothing in that flow removes anything, so storage only grows. A **cleanup policy** is the rule that bounds it: a named set of criteria, attached to one or more repositories, that a scheduled task evaluates to find components nobody needs any more and delete them. In Nexus Repository, cleanup policies and the tasks that apply them are **not configured by default**. An administrator creates a policy, attaches it to repositories, and lets the cleanup task run; until then a repository keeps everything that reaches it. ## The criteria a policy selects by The exact list differs by product and by format, but the same ideas recur. Nexus Repository names them like this: | Nexus criterion | What it measures | |---|---| | **Component Age** | days since upload or update in a hosted repository; days since the component was first downloaded into the cache in a proxy repository | | **Component Usage** | days since the last download; the published or updated date when it was never downloaded | | **Release Type** | releases or pre-releases; a Maven pre-release is a `-SNAPSHOT` version, an npm pre-release a version containing a dash | | **Retain Select Versions** | keep only the newest N versions of each component (an edition- and database-dependent option) | | **Asset Name Matcher** | a regular expression on the component's name, namespace or path | Three rules decide what a Nexus policy actually removes: - Inside one policy the criteria are **combined**: a component is removed only when it meets every condition set. - Several policies can be attached to the same repository, and their criteria may overlap. - Policies attach to **hosted** and **proxy** repositories, and not every criterion exists for every format; for Docker, cleanup evaluates only **tagged** manifests. Artifactory calls the same idea a **retention policy** (also known as a cleanup policy). Its settings include: - a **duration in days**, after which artifacts become candidates; - a **maximum number of unique versions or tags** to keep; - a package-type filter and **include/exclude path patterns**; - a cron schedule and a **dry run** that lists what would go. Separately, an Artifactory local repository has two per-repository limits that delete as new content arrives: **Max Unique Snapshots** for Maven snapshots and **Max Unique Tags** for Docker and OCI images. Both are unlimited by default, so they too do nothing until someone sets them. ## Snapshots and pre-releases Snapshot builds are the fastest-growing content in most repository managers. Every deploy of a Maven version such as `1.4.0-SNAPSHOT` stores another timestamped file in the same version directory, and that directory's `maven-metadata.xml` maps the base version to its timestamped builds. A busy project can leave thousands of them. - In Nexus Repository, a policy with Release Type set to pre-releases plus an age or usage criterion purges old snapshots; it replaces the older dedicated snapshot-deletion task. - In Artifactory, Max Unique Snapshots removes the oldest stored snapshot of an artifact each time a new one arrives beyond the limit. - Releases deserve a different, much longer rule, because a release is what something downstream may still depend on. ## Running a policy safely 1. **Write the criteria** for one repository and one format, never "all formats, all repositories" on the first try. 2. **Preview the result.** Nexus Repository's Preview Cleanup Policy Results lists the components that would be removed; Artifactory and Harbor offer a dry run. A preview is a point-in-time view: new uploads and downloads can change the real run. 3. **Attach and schedule.** In Nexus Repository the task *Admin - Cleanup repositories using their associated policies* applies the policies, by default once an hour. 4. **Reclaim the space.** The first stage of a Nexus cleanup only soft-deletes; a separate compaction task frees the disk. ## What a cleanup policy is not - It is not **garbage collection** of an OCI registry, which removes blobs no manifest references; a policy decides which components or tags go, and collection reclaims what they leave behind. - It is not the **withdrawal of a published release** for a security or legal reason, which is a deliberate act on one version rather than a rule over thousands. - It is not a guarantee that a deleted proxy component can be fetched again: re-downloading works only while the upstream still serves that version. A junior engineer who can name the criteria, explain that they combine, and insist on a preview before the first real run already avoids the most common cleanup incident: a broad policy that removed far more than anyone intended.

  • Why does component age mean something different on a Nexus proxy repository than on a hosted one?
    On a proxy repository, age counts from when the component was first downloaded into the cache; on a hosted repository, from upload or update. Removing a cached proxy component is usually cheap, because the next request fetches it from upstream again while the upstream still serves it. Removing a hosted component is final once the soft delete is compacted, because the hosted repository is the only copy.
  • If two cleanup policies are attached to one Nexus repository, how do they interact?
    Nexus Repository allows several policies on one repository and lets their criteria overlap, so each policy can remove the components that meet all of its own conditions. The AND applies inside a policy, not across policies. Harbor's tag retention works the other way round: its rules name what to keep, combine with OR, and anything no rule keeps is removed.

  • Repository managers clean up old versions by default, so no setup is needed.
  • Criteria inside one Nexus cleanup policy are ORed, so any single match deletes.
  • A component that was never downloaded can never match a last-download criterion.
  • Keep-the-newest-N counts across the whole repository rather than per component.
  • In Nexus Repository a cleanup run frees disk space the moment it finishes.
open as a page

Why does a cleanup run in Nexus Repository not free disk space at once, and what finally reclaims it?

level: middleimportance: must knowfreq 52%

basics

~20 s

Nexus Repository cleanup only soft-deletes: it marks components for removal, hides them and leaves their blobs on disk, still recoverable. Disk space returns only when the Admin - Compact blob store task hard-deletes soft-deleted blobs, scheduled per blob store.

open as a page

How does garbage collection in the open-source Distribution registry decide which blobs to delete, and why should writes stop while it runs?

level: middleimportance: should knowfreq 50%

basics

~20 s

Distribution registry garbage collection marks every digest that any manifest references, then sweeps and deletes every blob not marked. Writes must stop because a push uploads blobs before its manifest, so in-flight layers look unreferenced and get swept.

open as a page

After an OCI registry garbage collection that also removed untagged manifests, new replicas of a production service cannot pull its digest-pinned image. What happened, and how do you prevent it?

level: seniorimportance: should knowfreq 42%

basics

~20 s

The pinned manifest's only tag moved to a newer build, leaving it untagged, so collection with untagged deletion removed it and swept its unique layers. Prevent it with a retained, never-moved tag per deployed digest and dry runs checked against deployments.

open as a page

Your repository manager and registry hold 40 TB and grow 2 TB a month; what retention policy would you commit the organisation to, and why?

level: principalimportance: should knowfreq 30%

basics

~20 s

Classify content by what deleting it costs: proxy caches by last download, snapshots and per-commit builds by keep-newest-N, releases kept long, deployed digests exempt. Add previews, a soft-delete recovery window, a reclaim schedule, team quotas and an owner reviewing growth.

open as a page