Harbor Tag Pagination: Adjusting page_per_page Limits in v2.8+

Goal

We need to increase the number of tags retrieved per API call to reduce round‑trips for large repositories. The default page_per_page is 20, but Harbor 2.8+ allows up to 1000.

Constraints & Uncertainty

• Maximum page_per_page is 1000, configurable via harbor.ui.tagPaginationLimit in harbor.yml, requiring a restart.
• Large requests (>500 tags) risk exhausting database connections; performance drops sharply beyond 2000 tags per request.
• Offset‑based pagination can miss or duplicate tags if the tag set changes between pages; cursor‑based pagination is not supported.
• Some endpoints omit the X-Total-Count header introduced in v2.5, complicating client‑side pagination.

Unresolved Questions

1. What is the safe maximum page_per_page value that avoids exhausting database connections in a typical Harbor deployment?
2. Does the X-Total-Count header consistently match the total tag count returned by the API across all Harbor versions?
3. What mitigation strategy is recommended for offset‑based pagination to handle dynamic tag changes without missing or duplicating entries?