Development Setup & Contributing
Relevant source files
The following files were used as context for generating this wiki page:
Harbor Next is a community-driven evolution of the Harbor container registry, optimized for innovation and ease of contribution. This guide details the unified development environment, based on a containerized architecture with hot-reload capabilities, and outlines the standard contribution workflows required to maintain the automated release pipeline.
The project uses a hybrid development model where backend services run in Docker containers while the frontend can run natively or within the container network. Build automation and environment management are handled through Taskfile, replacing traditional Makefiles for faster, more modular operations.
Sources: README.md:12-25, devenv/README.md:5-9
Local Development Environment
The Harbor Next development environment is designed to be "out of the box," utilizing Docker containers and the air utility for Go hot reloading. This ensures that changes to backend logic are reflected in approximately 3 seconds without manual restarts.
Architecture Overview
The development environment consists of several interconnected services running within a dedicated Docker network. This setup avoids common localhost resolution issues between containerized components.
The diagram above illustrates the service dependencies and communication paths within the dev environment.
Sources: devenv/README.md:12-42
Prerequisites
| Tool | Version | Purpose |
|---|---|---|
| Task | v3.x | Build system and command runner |
| Docker / Podman | 20.10.10+ | Container engine for services and builds |
| Go | per versions.env | Backend compilation and unit testing |
| Bun | per versions.env | Frontend dependency management |
| Node.js | 16+ | Frontend builds and API client generation |
Sources: README.md:144-155
Common Task Commands
The project uses task for environment management. Key commands include:
| Command | Description |
|---|---|
task dev:up | Starts full environment (Backend in Docker, Portal native) |
task dev:infra:up | Starts only PostgreSQL, Redis, and Registry |
task dev:clean | Stops all services and removes associated volumes |
task build | Builds all Go binaries |
task test:quick | Runs fast validation (API lint + unit tests) |
task setup | Installs Go tools like air, dlv, and govulncheck |
Sources: README.md:166-179, Taskfile.yml:45-125, devenv/README.md:46-65
Contribution Workflow
Harbor Next enforces a strict PR-based workflow to support automated releases via release-please. Direct pushes to main are prohibited.
Branching and Commits
Contributors must follow the Conventional Commits specification. This format is parsed by CI to determine version bumps and generate the changelog.
This flow ensures every change landing on main is properly formatted for automation.
Sources: CONTRIBUTING.md:14-25, CLAUDE.md:13-18
Commit Types & Release Effects
| Type | Description | Release Effect |
|---|---|---|
feat | New user-facing feature | Minor Version Bump |
fix | Bug fix | Patch Version Bump |
feat! / fix! | Breaking change | Major Version Bump |
refactor | Code change (no behavior change) | No Release |
docs | Documentation only | No Release |
ci / chore | Maintenance or pipeline changes | No Release |
Sources: CONTRIBUTING.md:45-58, CLAUDE.md:21-23
Merging Requirements
When a PR is approved and CI passes, maintainers must always use "Squash and merge".
- Reason: Non-squash merges create
Merge pull request #Ncommits that do not follow conventional formats, which breaks therelease-pleaseautomation. - DCO: Every commit must be signed off (
Signed-off-by: Name <email>). This can be automated usinggit commit -s.
Sources: CONTRIBUTING.md:105-125, CLAUDE.md:17
Development Guidelines
Backend Development
Backend services run under Delve by default within the containers, allowing for remote debugging. Air configuration files (air.core.toml, etc.) manage the hot-reload boundaries.
Sources: devenv/README.md:73-82, devenv/README.md:88-95
Frontend Development
The Harbor UI is built using Angular and the Clarity Design System.
- Node Version: Must match the version in
.nvmrc. - API Client: The TypeScript API client is automatically regenerated from
swagger.yamlduringnpm installor viatask build:gen-apis. - Proxy: A
proxy.config.mjsmaps frontend requests to the containerized Core API (defaulting tolocalhost:8080).
Sources: src/portal/README.md:7-27, README.md:152-154
Testing Artifacts
To push images to the local dev environment, localhost:8080 must be added to the Docker engine's insecure-registries list.
docker login localhost:8080 -u admin -p Harbor12345
docker tag my-image:latest localhost:8080/library/my-image:latest
docker push localhost:8080/library/my-image:latest
Sources: devenv/README.md:104-125
Conclusion
By standardizing on Taskfile and containerized environments, Harbor Next provides a consistent experience across local development and CI pipelines. Adherence to Conventional Commits and the "Squash and Merge" policy is critical for the maintenance of the project's automated release lifecycle.