Cleanup Policies, Retention, Component Age, Last-Downloaded Rules, Preview, and Storage Reclamation: Configuration, Design Choices, and Tradeoffs

1. Retention is a service-level decision

A cleanup policy converts business and delivery assumptions into deletion eligibility. That means the first design question is not “30 or 90 days?” It is “what evidence must remain available for rollback, incident reconstruction, compliance, offline development, rebuild reproducibility, and vulnerability response?” Different artifact classes have different answers.

A repository platform with no cleanup eventually loses capacity headroom. A repository platform with aggressive uniform cleanup can lose the exact release needed during an incident. Production retention therefore needs a declared retention SLA: class of content, minimum survival window, usage exception, release protection, reclaim delay, owner, review cadence, and recovery source.

2. Five dimensions shape a safe policy

3. Development artifacts and releases should rarely share the same retention rule

CI can create hundreds of ephemeral builds per day. Most are valuable only until the next successful build or for a short debugging window. Releases can remain operational dependencies for months or years because rollback, long-lived branches, customer installations, or downstream systems still reference them.

flowchart TD
CI[CI build] --> D[Development repository]
D -->|short retention| X[Cleanup candidate]
CI -->|approved immutable build| R[Release repository]
R -->|support / rollback window| K[Longer retention]
K -->|policy + validated recovery| Y[Later cleanup]
X --> C[Compaction after verification]
Y --> C

Separating repositories can make policy easier to reason about because repository boundary becomes lifecycle boundary. A single repository can still work when format metadata and criteria distinguish prereleases/releases safely, but operational evidence becomes harder to audit.

4. Last-downloaded is a signal, not a universal truth

Usage-based cleanup is attractive because it retains what people actually consume. It also inherits every assumption in request tracking. Package managers may use metadata requests, HEAD requests, local caches, group repositories, proxy caches, or offline build caches in ways that make “downloaded” differ from “needed.” A release can be critical yet rarely fetched because clients already cache it.

Before relying on last-downloaded, test representative clients against the exact Nexus version and format. The 3.94.0–3.95.2 Docker known issue is a concrete example: some manifest HEAD requests do not update lastDownloaded, so active images can appear stale. In such a condition, usage-based Docker cleanup should be disabled rather than compensated with guesswork.

5. One broad policy versus repository-specific policies

In 3.95, policy administration can associate a policy with multiple repositories from the policy screen. That improves usability but does not reduce the blast radius of a broad rule. Treat bulk association as configuration convenience, not as proof that those repositories belong under one lifecycle contract.

6. Choose criteria to encode intent, not to chase a storage number

Suppose a team keeps 14 days of debug builds but wants unused artifacts gone after 7 days. If builds are generated daily, an age threshold around 14 days may approximate the minimum debug window, while usage can protect older builds still being consumed. For release content, a fixed age may be inappropriate unless the release support policy has an explicit end-of-life mechanism.

These numbers are examples, not defaults. Production values must come from build cadence, release policy, recovery objective, and measured storage growth.

7. Optional Pro/PostgreSQL design: retain N recent versions

Current 3.95 documentation expands Retain Select Versions to versioned formats that have version semantics. It remains a Pro feature with PostgreSQL requirements in current cleanup documentation. Use it when a version floor materially reduces rollback risk—for example, “eligible if inactive for 90 days, but always keep the newest three release versions.”

Do not treat N as an integrity guarantee. A package may have three semantically newer versions that are all broken, revoked, or incompatible with a downstream system. Release governance should still record approved artifact identity, provenance, and support status.

8. Cleanup frequency and compaction frequency need not be equal

Policy evaluation and soft deletion can run relatively often, while blob compaction may be more IO-intensive and destructive. Current Nexus creates system cleanup tasks with regular schedules, but operators can reschedule them. Production design should consider repository traffic, database load, blob-storage latency, backup windows, and recovery acceptance.

9. Retention cost is larger than blob bytes

Long retention consumes blob capacity, database rows, indexes/search state, backup bandwidth, object-store requests, restore time, and operator attention. Short retention reduces those costs but increases rebuild risk, upstream dependence, and incident friction. A proxy cache with 30-day inactivity cleanup can reduce stale vulnerable components and storage, but it also means an upstream outage could matter more if needed dependencies were evicted.

Therefore tie proxy retention to resilience: if builds must continue during a public-registry outage, the working set must remain cached long enough and clients must use Nexus rather than bypassing it.

10. Security and retention have competing goals

Removing unused vulnerable packages reduces dormant attack surface and accidental reuse. Preserving releases and forensic evidence supports incident response. Neither goal implies “delete vulnerabilities immediately everywhere.” An artifact under investigation may need preservation even if blocked from normal consumption. Repository cleanup, quarantine/policy systems, and legal/forensic retention are separate controls.

Least privilege matters too. Current cleanup docs distinguish permissions for policy creation, repository attachment, and task modification. A CI publisher should not automatically be able to redefine cleanup rules or compact blob stores.

11. Worked design: internal Maven, npm, PyPI, and proxy caches

Assume 80 developers, daily CI, monthly releases, and a 60-day rollback requirement. Storage grows 8 GiB/day, mostly CI prereleases. The team uses Community Edition today but may move to Pro/PostgreSQL later.

If Pro/PostgreSQL is introduced, retain-last-N can become an additional guardrail for versioned repositories, but it does not replace release/EOL governance.

12. Decision record template

repository: maven-dev-hosted
owner: build-platform
purpose: ephemeral CI and SNAPSHOT artifacts
format: maven2
repository_type: hosted
retention_intent:
  minimum_debug_window_days: 21
  inactivity_days: 14
  release_protection: "releases stored elsewhere"
execution:
  preview_required: true
  cleanup_window: "off-peak"
  compact_after_validation: true
  soft_delete_grace_days: 7
recovery:
  source: "validated Nexus backup"
  rpo: "24h"
  restore_test: "quarterly"
known_issues:
  - "re-check version-specific cleanup release notes before changes"

The YAML is documentation, not Nexus configuration. Its value is that a future operator can compare business intent with the actual policy before changing anything.

13. Design mistakes to avoid

• Applying one retention age to development, releases, and proxies because it is administratively convenient.
• Using last-downloaded without testing whether representative clients update it reliably.
• Running compaction immediately after cleanup, eliminating a useful soft-delete grace window.
• Assuming backups are valid because a job says “success” without restore testing.
• Using Pro-only retain-last-N as a hidden dependency in a Community operating runbook.
• Optimizing for reclaimed GiB while ignoring build-outage and rollback costs.

14. Knowledge check

15. Summary and next step

A production retention policy is an SLA encoded as criteria, scope, schedule, recovery window, and evidence—not a universal age number. Lesson 4 takes these design choices into failure analysis: broad regexes, misunderstood timestamps, ignored preview, delayed reclamation, task overlap, and direct filesystem deletion.

Official references and version notes

• Sonatype: Cleanup Policies — current criteria, preview, system cleanup tasks, soft deletion, compact-blob-store reclamation, and format matrix.
• Sonatype: Nexus Repository 3.95.x Release Notes — 3.95 cleanup enhancements and current known issues.
• Sonatype: Tasks — current task types including Admin - Compact blob store.
• Sonatype: Keeping Disk Usage Low — supported cleanup/reclamation guidance and the separation between deletion and freed disk space.
• Sonatype: Administration Best Practices — cleanup cadence and storage-management recommendations.
• Sonatype: Staging Concepts — aligning repository lifecycle and cleanup.