Introduction to Harbor Next
Relevant source files
The following files were used as context for generating this wiki page:
Harbor Next is a community-driven evolution of the CNCF-graduated Harbor project. It is designed to accelerate innovation and lower barriers for contributors while serving as the upstream foundation for the 8gears Container Registry (8gcr). As an enhanced fork, it maintains compatibility with the core Harbor ecosystem while prepending vetted features and automation not yet present in the upstream project.
Sources: README.md:12-19, CLAUDE.md:3-3
The platform serves as a secure, cloud-native registry for storing container images and OCI artifacts. It provides robust security features including Role-Based Access Control (RBAC), vulnerability scanning, artifact signing, and policy-based replication across hybrid and multi-cloud environments.
Sources: README.md:6-9, README.md:31-48
Core System Architecture
Harbor Next utilizes a microservices-oriented architecture typically deployed via Docker Compose or Helm Charts. The system is composed of several specialized components coordinated by a central "Core" service.
Component Interaction Flow
The diagram below illustrates how user requests are handled through the Portal (Nginx) and distributed to the internal services.
The Portal serves the Angular UI and acts as a reverse proxy for API and registry traffic. The Core service handles the business logic, authentication, and gateway functions.
Sources: deploy/compose/README.md:62-95
Major Functional Components
| Component | Description |
|---|---|
| Core | API gateway, authentication, authorization, and project management logic. |
| Portal | Nginx-based frontend serving the Angular web interface and routing traffic. |
| Job Service | Manages asynchronous tasks such as replication, garbage collection, and scanning. |
| Registry | Based on Docker Distribution (V3 in Harbor Next) for handling artifact push/pull. |
| Trivy Adapter | Provides vulnerability scanning capabilities for uploaded artifacts. |
| Database | PostgreSQL (>= 12) for storing persistent metadata, users, and projects. |
| Sources: README.md:27-27, deploy/compose/README.md:62-95, CHANGELOG.md:104-105 |
Key Features and Enhancements
Harbor Next introduces several notable changes to the base Harbor project to improve the developer experience and system performance.
Enhanced Artifact Management
Harbor Next supports multi-architecture artifacts and scratch images with minimal attack surfaces. It has evolved to support the OCI Distribution Spec v1.1.0, including referrers API and SBOM (Software Bill of Materials) management.
Sources: README.md:21-29, CHANGELOG.md:53-54, CHANGELOG.md:85-87
Replication and Proxy Cache
The system supports sophisticated replication policies and proxy caching:
- Proxy Cache: Supports syncing state with upstream registries, including deleting local cache when artifacts are removed upstream. Sources: CHANGELOG.md:16-17
- Diverse Adapters: Integration with ACR, VolcEngine, and JFrog Artifactory. Sources: CHANGELOG.md:46-47, CHANGELOG.md:55-55, CHANGELOG.md:131-131
- Single Active Replication: A feature to prevent parallel runs under the same policy to avoid resource contention. Sources: CHANGELOG.md:18-19
Security and Governance
Security is managed through multiple layers of protection:
- RBAC: Fine-grained permissions based on projects.
- Scanning: Default integration with Trivy for CVE reports, now supporting
fixVersion. Sources: CHANGELOG.md:20-20 - Signing: Support for Cosign artifact signing and verification. Sources: CHANGELOG.md:166-166
- OIDC/LDAP: Enterprise-grade identity provider integration with PKCE and session logout support. Sources: README.md:43-48, CHANGELOG.md:32-32
API and Integration
The Harbor Next API follows the RESTful paradigm and is primarily versioned at v2.0. The API provides endpoints for administrative operations, repository management, and system health monitoring.
Core API Endpoints
| Category | Base Path | Description |
|---|---|---|
| Health | /health | Status check for all Harbor components. |
| Projects | /projects | CRUD operations for projects and their metadata. |
| Artifacts | /projects/{project}/repositories/{repo}/artifacts | Management of images, charts, and OCI artifacts. |
| Users | /users | User management and profile updates. |
| Replication | /replication/policies | Orchestration of artifact synchronization rules. |
| Sources: api/v2.0/swagger.yaml:18-200 |
Artifact Retrieval Sequence
The following sequence diagram shows the logic for retrieving an artifact through the Harbor API.
Development and Contribution
Harbor Next emphasizes a modern development workflow to lower entry barriers for new contributors.
Local Development Environment
The project uses Taskfile (replacing traditional Makefiles) to automate builds and local environment setup.
- Backend: Written in Go.
- Frontend: Angular-based UI built with the Clarity Design System.
- Hot Reload: The
task dev:upcommand provides a hybrid development environment with hot reload capabilities.
Sources: README.md:64-75, CLAUDE.md:6-12
Contribution Workflow
The project strictly enforces Conventional Commits and requires DCO (Developer Certificate of Origin) sign-off on all commits.
- Branching:
feat/orfix/prefixes are required. - Merging: Only "Squash and merge" is permitted on GitHub to maintain a clean history for the automated
release-pleasetool. - Automated Releases: Version bumps (Major/Minor/Patch) are determined automatically based on commit types (e.g.,
feat!:triggers a major version bump).
Sources: CONTRIBUTING.md:16-100, CLAUDE.md:14-22
Summary
Harbor Next represents a significant modernization of the Harbor registry. By focusing on contributor ladder automation, continuous delivery, and advanced OCI features like SBOM management and OCI v1.1.0 support, it provides a highly scalable and secure foundation for enterprise container management. Its architecture ensures high availability while its enhanced development tooling fosters rapid innovation within the community.
Sources: README.md:21-30, ROADMAP.md