Harbor: a CNCF container registry with RBAC, replication and vulnerability scanning

What Harbor adds on top of Docker Distribution

Plain Docker Distribution stores and serves blobs. It has no notion of a team, a project, or a policy. Harbor is built as an extension of that distribution layer, and the README lists what the extension contains: projects with role-based access control, policy-based replication between registries, vulnerability scanning with policy checks, LDAP and AD integration, OIDC single sign-on, garbage collection, a graphical portal, audit logs and a RESTful API.

The audience follows from that list. A single developer running a local registry does not need any of it. A platform team that has to answer who pushed this image, whether it has known vulnerabilities, and whether it is allowed into production does. Harbor is hosted by the Cloud Native Computing Foundation, and the README notes that the project holds bi-weekly community calls in two timezones, which tells you the intended scale of adoption.

The README also states the reason a registry close to the build and run environment matters: image transfer efficiency. That is a performance argument for colocating the registry with the cluster, separate from the governance features.

Projects, policies and the components behind the portal

The organising unit in Harbor is the project. A user gets different permissions on images or Helm charts inside a project, which is how role-based access control is expressed. Authentication can come from Harbor itself, from an enterprise LDAP or AD directory, or from an external identity provider over OpenID Connect, in which case single sign-on covers the portal.

Replication is policy based. A policy carries filters on repository, tag and label, and the README states that Harbor retries a replication automatically when it hits an error. The stated uses are load balancing, high availability and multi-datacenter deployments across hybrid and multi-cloud setups. That retry behaviour is the interesting part: replication is treated as an eventually-consistent background process rather than a synchronous mirror, so a policy is not a guarantee that the destination is current at any given moment.

Scanning runs regularly against images, and policy checks can block vulnerable images from being deployed. Garbage collection is a separate administrator-run job that removes dangling manifests and unreferenced blobs to reclaim space. Both of these are jobs, not continuous daemons, so their effect depends on someone scheduling them.

Administrative work is exposed through RESTful APIs, and the README points to an embedded Swagger UI for exploring and testing them. The architecture is documented separately in the project wiki under Architecture Overview of Harbor; the README itself does not describe the internal service topology.

Installing Harbor from a release and pushing a first image

The README gives system requirements for a Linux host: docker 20.10.10-ce+ and docker-compose 1.18.0+. It directs you to download the binaries from the Harbor releases page and then follow the Installation & Configuration Guide at goharbor.io. There is no one-line installer command in the README, so treat the guide as the source of truth for the configuration file.

One warning in the README is worth repeating verbatim in effect: the main branch may be in an unstable or even broken state during development, and releases should be used instead to get a stable set of binaries. Do not build from main for anything you depend on.

Starting with v2.15.0, release artifacts are signed with Cosign, and the README shows a verification command. The example below is the quick verification path from the README, using an offline installer tarball and its signature bundle. The flags name the OIDC issuer and an identity regexp tied to the project's GitHub Actions workflow, so a passing check ties the artifact to that build pipeline.

# Install Cosign (v2.0+)
brew install sigstore/tap/cosign

# Verify signature
cosign verify-blob \
  --bundle harbor-offline-installer-v2.15.0.tgz.sigstore.json \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github.com/goharbor/harbor/.github/'

Note that the README's snippet is truncated at the identity regexp, and the signature bundle file name follows the installer it belongs to, so substitute your own release version. After the installer runs, the practical first use is a docker login against the Harbor host followed by a push, but the README does not spell out those commands; the documentation site covers usage.

For Kubernetes, the README is explicit: use the Harbor chart in the goharbor/harbor-helm repository rather than the Compose path. A Harbor Operator is also mentioned as a more recent deployment option, without further detail in the README.

Where Harbor is the wrong choice

The first limitation is operational weight. Deploying through Docker Compose or the Helm chart means running a multi-service system, and the README's feature list implies state that has to be backed up and upgraded: projects, users, policies, scan results and audit logs. If your requirement is a dumb blob store for a small number of images, that weight buys you nothing.

Scanning is only as useful as its configuration. The README says images are scanned regularly and that policy checks can prevent vulnerable images from being deployed, but it does not describe a default schedule, a default severity threshold, or what happens when the scanner itself is unavailable. A team that assumes scanning is on and blocking by default may be wrong, and the README will not correct that assumption.

Replication retries automatically, which is good for transient failures and bad for expectations. It is a policy-driven background process with filters, not a synchronous guarantee, so a deployment that reads from a replica immediately after a push can still miss the image.

Garbage collection is manual and administrator-run. Until someone runs it, dangling manifests and unreferenced blobs keep consuming storage. Nothing in the README suggests automatic reclamation.

Finally, the README only documents part of the API surface. It links to a Swagger document described as covering new or changed APIs, which suggests the full administrative API is documented elsewhere, and the README does not document rollback or downgrade procedures for a deployment.

Harbor compared with a plain Docker registry

The obvious alternative is the upstream Docker Distribution registry that Harbor itself extends. The difference in approach is stark. Docker Distribution is a single service that implements the OCI distribution protocol: it stores and serves content and leaves authentication to whatever you put in front of it, often a token service you write or configure yourself.

Harbor takes the same distribution layer and adds the surrounding system: projects as the permission boundary, roles inside them, LDAP/AD or OIDC for identity, replication policies between instances, scanning with policy checks, a portal, audit logs and a RESTful API with Swagger UI. The OCI Distribution Conformance Tests badge in the README indicates the distribution behaviour is still expected to conform, so you are not trading protocol compatibility for the extra features.

What you trade is operational surface. A plain registry is one thing to run. Harbor is a deployment with a database, a portal, background jobs for scanning and replication, and an upgrade path you have to follow release by release. If your only problem is storing images, the upstream registry solves it with far less to operate. If your problem is governing who can push what, where it is allowed to run, and whether it has known vulnerabilities, the upstream registry does not address it at all.

Licence, releases and the cost of staying current

Harbor is licensed under Apache-2.0. That is a permissive licence, and it means you can use, modify and redistribute the project, including in commercial settings, subject to the terms of the licence text itself. This is a description of the licence identifier, not legal advice; read LICENSE in the repository for the actual terms, and check the licences of components Harbor pulls in if you redistribute a modified build.

The repository is not archived, and the last push was on 2026-09-18. Recent releases are v2.15.3-rc1 on 2026-09-11, v2.15.2 on 2026-07-02, and v2.15.2-rc3 on 2026-07-02. The pattern is worth reading carefully: release candidates appear before the stable release, and the stable line is v2.15.x. If you want stability, track the non-rc tags.

Upgrade cost is the part the README does not cover. It points to the Installation & Configuration Guide and to the documentation site for more detail, and it documents release signature verification from v2.15.0 onward, but it does not describe a downgrade path. The main branch warning is the clearest maintenance signal in the README: development happens on main, users are expected to consume releases. Plan upgrades around release tags rather than around the branch.

Editorial conclusion

Adopt Harbor if you need a private registry with projects, role-based access, LDAP or OIDC login, replication between sites and scanning policy, and you can run Docker Compose or the Helm chart. Do not adopt it if you only need a single-tenant blob store for a handful of images, or if you cannot operate the database, cache and storage that the deployment brings along. Before committing, read the Installation & Configuration Guide, pick a release rather than the main branch, and confirm which database and storage backend your deployment will use.

Frequently asked questions

Official sources

1. goharbor/harbor on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases