goharbor / goharbor/harbor-cli

[feature]: implement registry-wide Garbage Collection (gc) command group

Open
#1,017 3 comments 0 reactions 0 assignees View on GitHub
enhancement status/accepted status/needs-feedback
Dominant language
Go
Stars
163
Forks
211
Avg merge
1m
Merged PRs (30d)
1

Description

### Problem / Limitation (Before State)
Currently, `harbor-cli` lacks support for managing registry-wide Garbage Collection (GC) operations.

**What was happening earlier:**
1. **No Terminal Automation:** Registry administrators automating cluster maintenance or performing cleanup tasks inside CI/CD pipelines had no way to trigger or monitor registry GC jobs via the terminal.
2. **Forced Context-Switching:** Administrators were forced to leave their terminal, open the Harbor WebUI, log in, navigate to Admin -> Garbage Collection, and manually trigger or inspect runs.
3. **No Log Auditing:** Inspecting which blobs were deleted or checking for storage/permission errors during a GC run required manual download of execution logs from the WebUI.
4. **Schedule Limitations:** Modifying automatic GC cron schedules required WebUI interactions.

---

### Motivation & Value
Implementing the `gc` command group directly advances the project towards its core goal of **WebUI Feature Parity**. It empowers operations teams to perform complete administrative cleanup workflows programmatically.

---

### Proposed Architecture & Command Structure
We propose introducing a native `gc` subcommand group under the `system` category. The commands leverage the SDK's existing `client.GC` endpoints:

1. **`harbor gc history`**
* *Purpose:* Displays a formatted table of all past GC executions.
* *Flags:* Supports pagination (`--page`, `--page-size`), queries (`--query`), and sorting (`--sort`).
2. **`harbor gc schedule`**
* *Purpose:* Displays the current automatic GC schedule (type, cron expression, next execution time, and settings).
3. **`harbor gc trigger`**
* *Purpose:* Triggers an immediate manual GC execution.
* *Flags:* `--delete-untagged`, `--dry-run`, and `-i/--interactive` (launches a visual `huh` prompt to select options).
4. **`harbor gc log [gc-id]`**
* *Purpose:* Fetches and outputs the raw text execution log for a specific GC job.
5. **`harbor gc stop [gc-id]`**
* *Purpose:* Instantly stops a currently running GC execution to prevent resource exhaustion during peak hours.
6. **`harbor gc update-schedule [schedule-type]`**
* *Purpose:* Updates the automatic schedule config (`none`, `hourly`, `daily`, `weekly`, or `custom`).
* *Flags:* `--cron` (for custom types), `--delete-untagged`, `--dry-run`, and `-i/--interactive`.

---

### Alternatives Considered
1. **Option A (Trigger-Only):** Only implement `trigger` and `history`. This was rejected because log auditing and stopping jobs are critical for operational safety when performing deletions.
2. **Option B (Complete Group - Chosen):** Implement the full control loop (trigger, stop, log, schedule, history) to ensure administrative completeness.

Contributor guide

Open the contributing guide

Research direction

Start by inspecting the existing CLI command structure and the SDK's client.GC endpoints referenced in the proposal. Define the gc command group under the system category, then verify that history, schedule, trigger, log, stop, and update-schedule support the listed arguments and flags and complete the corresponding administrative workflows.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli, devops
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.