Scheduled Tasks, Repair Jobs, Metadata Rebuilds, Blob Maintenance, and Operational Housekeeping: Concepts, Architecture, and Mental Model

1. The practical problem: maintenance is code that runs against repository state

By Chapter 18 you already know that cleanup is not a filesystem deletion shortcut. Chapter 19 generalizes that lesson: Nexus Repository contains server-side jobs that can clean, rebuild, reconcile, back up, recalculate, move, or otherwise transform repository-related state. These jobs are called tasks.

A task can be harmless, expensive, destructive, recovery-oriented, edition-specific, or obsolete for your version. Treating every task as “maintenance” hides the most important engineering question: what state does this particular task read or mutate, and what evidence proves it should run?

The safest operator learns the task model first, then selects a task. The unsafe operator starts from an old blog post, searches for a similarly named menu item, and clicks Run.

2. Mental model: definition → eligibility → execution → evidence → recovery

flowchart TD
I[Operator intent / incident evidence] --> T[Task type]
T --> C[Task configuration + scope]
C --> S[Schedule or Run now]
S --> Q[Scheduler / execution state]
Q --> D[Database / metadata / blob / log work]
D --> H[Task history + task log + nexus.log]
H --> V[Independent verification]
V --> R[Close / reschedule / rollback or recovery]
P[Privileges] --> C
W[Maintenance window + capacity] --> S
X[Version / edition / task availability] --> T

The first arrow is intentional: operational intent should select the task, not the other way around. A search problem may justify a search-index rebuild. A corrupted Maven metadata problem may justify a Maven metadata rebuild. A storage-capacity problem does not automatically justify either.

3. Anatomy of a Nexus task

4. Task categories are safety hints, not interchangeable labels

Current Sonatype documentation groups tasks by prefixes. The prefix tells you the operational intent:

• Admin tasks cover recurring administration such as cleanup, H2 backup, blob compaction, and temporary-file cleanup.
• Format-specific tasks maintain package metadata, indexes, incomplete uploads, snapshots, or format-specific structures.
• Repair tasks are incident-oriented. They are not a weekly hygiene checklist.
• Repository tasks perform functions such as import/export or repository/blob movement; some are Pro-only.
• Statistics tasks recalculate or populate metrics rather than repairing artifact bytes.

The category is only a starting point. You still need the exact type description, version notes, repository/format scope, database requirements, and data-loss warnings.

5. Run now and recurring schedules create the same responsibility

Clicking Run avoids future recurrence but does not make an operation safe. Conversely, a recurring schedule does not make a task routine. A correct schedule is simply a repeated execution policy for a task whose behavior is already understood.

The Advanced schedule documented by Sonatype includes a seconds field. Do not paste a five-field Unix crontab expression without checking the Nexus syntax.

6. Task history is a summary; logs are execution evidence

The Tasks table exposes last run, last result, next run, and current status. That is useful for triage, but a result such as SUCCESS does not prove your business objective. A rebuild can complete successfully yet target the wrong repository. A cleanup can succeed and still represent the wrong retention policy.

Current Sonatype documentation places task logs under:

$data-dir/log/tasks

Run-specific task log files are normally configured for removal after 30 days. Task output may also appear in nexus.log, and some tasks log only there. For long-running tasks, progress can also be emitted periodically to nexus.log. Preserve incident-relevant logs before their retention window expires.

7. Rebuild is not recovery: name the state layer first

If the bytes are gone, a search-index rebuild cannot recreate them. If only search is stale, a full data-repair workflow is disproportionate and can introduce risk.

8. Task availability changes across versions

Task names are not timeless API contracts. Current examples include Repair - Repository trim browse tree added in 3.88.0, Repository - Copy Blob Size to Asset Table added in 3.90.0, and format-specific additions in 3.95.0 such as Composer metadata rebuild and a Pro NuGet symbol-index rebuild. Older reconcile tasks have been replaced or constrained.

9. Three examples of stale maintenance folklore

1. “Schedule every Repair task weekly.” Current documentation says Repair tasks are for specific issues; blanket recurring repair can waste IO and complicate incidents.
2. “Run Reconcile component database from blob store whenever search looks wrong.” Current data-repair tasks introduced in 3.83 replace the old reconciliation workflow for recovery scenarios; neither is a normal search fix.
3. “Use Admin - Execute script for custom housekeeping.” The task was disabled as a security measure in 3.21.2, and Sonatype now directs automation toward UI/REST APIs; Groovy scripting is on a deprecation path.

10. Least privilege for task operators

Current privilege documentation separates task capabilities. nx-tasks-read allows viewing, while nx-tasks-run covers start/stop. Create, update, and delete have separate privileges, and nx-tasks-all grants all task permissions. This enables a useful separation of duties: an on-call operator can inspect and run an approved task without receiving the right to redesign every task definition.

Be careful with the task type itself. A narrowly scoped task privilege can still launch a powerful task definition created by someone else. Least privilege is the combination of role permissions, pre-approved task definitions, and procedural change control.

11. Read-only and execution API mental model

The Tasks API supports listing and inspecting task records, and provides run/stop operations. Current documentation places create/update/delete/task-template endpoints under the Pro section, so the mandatory Community Edition lab does not depend on API-based task provisioning.

# Disposable lab only. Do not put a real password in shell history.
export NEXUS_URL='http://127.0.0.1:8081'
export NEXUS_USER='task-observer'
read -rsp 'Temporary lab password: ' NEXUS_PASS; echo

curl -fsS -u "$NEXUS_USER:$NEXUS_PASS" \
  "$NEXUS_URL/service/rest/v1/tasks"

Interpret the response as server scheduler state, not repository content. Fields such as task ID, type, current state, last run/result, and next run help correlate UI, API, and log evidence.

12. Maintenance windows are resource budgets

A maintenance window is not merely “after midnight.” It is a period where the platform has enough IO, database headroom, heap/direct memory, file handles, and operational attention for the job. Two individually safe tasks can be unsafe together if both scan millions of assets or contend for the same blob store.

Before scheduling, record: expected scope, previous duration, database/blob IO, client traffic, backup window, cleanup/compaction windows, migration/upgrade activity, and the recovery plan if the task exceeds its window.

13. Read-only preflight checklist

1. Record Nexus version, edition, Java version, database, blob-store type, and free disk.
2. Open Settings → System → Tasks and export/screenshot the current task table.
3. Identify auto-created tasks separately from operator-created tasks.
4. For the candidate task, open current Sonatype documentation and record its exact type ID if documented.
5. Identify repository/blob-store scope and whether the task is Admin, format, Repair, Repository, or Statistics.
6. Read the last task result and task log before changing the schedule.
7. Check concurrent maintenance windows and active uploads/build traffic.
8. Confirm the account has only the task permissions required for the operation.

14. Why this matters in DevOps

Build pipelines depend on repository availability and metadata correctness, but repository maintenance competes for the same database, disk, blob-store, and network resources. Treating tasks as observable state transitions lets teams automate recurring hygiene without turning maintenance into an unexplained source of latency, missing packages, or corrupted recovery state.

15. Knowledge check

16. Summary and next step

You now have the task operating model: intent selects a current task type; scope and privileges constrain it; schedule and capacity determine when it may run; task history and logs show what happened; independent verification proves whether the repository objective was achieved. Lesson 2 turns that model into a safe local workflow without normalizing Repair tasks as housekeeping.

Official references and version notes

• Sonatype: Tasks — task states, schedules, logs, current task catalog, and Repair-task cautions.
• Sonatype: Tasks API — list/get/run/stop operations and Pro-only create/update/delete/template endpoints.
• Sonatype: Data Repair Tasks — current plan/execute workflow and recovery-only use.
• Sonatype: Cleanup Policies — cleanup-system tasks, soft deletion, and compact-blob-store reclamation.
• Sonatype: Privileges — nx-tasks-read, nx-tasks-run, create/update/delete task privileges, and least-privilege design.
• Sonatype: Nexus Repository 3.95.0–3.95.2 Release Notes — dated feature and maintenance-task changes.
• Sonatype: System Requirements — Java 21, database guidance, storage, and capacity prerequisites.