How to migrate from Docker Hub to Harbor
Move from Docker Hub to Harbor: list every image reference, replicate your repositories, proxy public images, replace teams and tokens, then cut over.
In short
- Harbor copies your Docker Hub repositories with a pull-based replication rule, filtered by name and tag and run manually or on a schedule. Manifests are copied unchanged, so digests stay the same.
- Public base images keep coming from Docker Hub through a Harbor proxy cache project, which signs in with a Docker Hub account and checks for new versions with requests Docker does not count.
- Teams and access tokens do not come across: directory groups become project members with a role, and each pipeline or cluster token becomes a robot account limited to one project.
- Image references are most of the work: every Dockerfile, pipeline, Helm values file, manifest and compose file that names docker.io, or a bare name such as nginx, changes.
On this page (9)
Moving from Docker Hub to Harbor is a copy and a re-pointing. Harbor copies your own repositories from Docker Hub with a replication rule, and keeps fetching public base images from Docker Hub through a proxy cache. What does not come across is the organisation around the images: teams, access tokens, automated builds and Docker Scout. Most of the work is in the references, because every place that names an image changes to your registry’s hostname. This guide covers the order we do it in, and the places it usually goes wrong.
Why teams move from Docker Hub to Harbor
Three reasons come up again and again.
- Images next to where they are built and run. Harbor runs on your network, beside the build agents that push and the clusters that pull. Private images stay off a public service, and a deployment does not depend on the internet to fetch your own code.
- Fewer pulls across the internet. A proxy cache serves each public base image from Harbor once it has been fetched. Harbor checks Docker Hub for a newer version with a HEAD request, which Docker does not count as a pull.
- Scanning and policy in the registry. Trivy scans images on push, and a project can refuse pulls of images at or above a severity you choose, or of images without a Cosign or Notation signature. Retention, tag immutability and quotas sit beside them, all in the Apache-2.0 release, with no paid edition.
What you give up is Docker Hub as a public catalogue: images you publish for customers or the open-source community stay on Docker Hub. Harbor does not build images, so automated builds move into your CI, and Docker Scout’s analysis stays with Docker. And someone has to run the registry, which is the part Pilae takes on.
Step 1: list every image reference
The references decide the length of the project, so find them first. Search every repository, not only the application ones:
| Where | What names an image |
|---|---|
| Dockerfiles | Every FROM line, in every stage of a multi-stage build |
| CI pipelines | image: keys, docker build, push and pull steps, login steps |
| Helm values | image.repository, often with the registry in a separate key |
| Kubernetes manifests | image: in Deployments, StatefulSets, Jobs, CronJobs, init containers |
| Compose files | image: in every service |
A bare name defaults to Docker Hub: nginx means docker.io/library/nginx, and acme/api means docker.io/acme/api. Search for bare names as well as docker.io, index.docker.io, registry-1.docker.io and registry.hub.docker.com. Put each reference in one of two groups: one of your repositories, which moves by replication in step 3, or a public image, which goes through the proxy cache in step 4.
Then take stock on the Docker Hub side:
- Repositories. Docker documents an export of an organisation’s repositories through the Docker Hub API, with each one’s visibility, last update and pull count. A repository that no reference names and nobody has updated in a long time is a candidate to leave behind.
- Teams and permissions. Each repository’s Permissions tab shows which teams have Read-only, Read & Write or Admin access.
- Tokens. Personal access tokens and organisation access tokens, with their Last used column, show which pipelines and clusters sign in to Docker Hub.
- Automated builds and webhooks. A repository’s Builds tab, then Configure automated builds, shows its source repository, build rules and build environment variables. Webhooks are listed per repository.
- Credentials on clients.
imagePullSecretsin each Kubernetes namespace whose server ishttps://index.docker.io/v1/,credsStoreandcredHelpersin~/.docker/config.jsonon build agents, and Docker Hub tokens stored as CI variables.
Step 2: set up sign-in, projects and robot accounts
Choose sign-on before anyone else signs in. Harbor switches from its own user database to OIDC only while no user other than admin exists, so this is the first change on a new instance.
- OIDC. In Keycloak or your identity provider, register Harbor as a client with the redirect URI Harbor shows at the bottom of its authentication settings, and add a group claim to the ID token. In Harbor, set the Group Claim Name, an OIDC Admin Group, and Automatic onboarding with a Username Claim. The docker CLI cannot follow a browser sign-in, so each person uses the CLI secret from their Harbor profile as a password.
- Projects. One project per Docker Hub namespace keeps paths familiar; one per team keeps permissions simple. Add each directory group as a project member with a role.
- Robot accounts for every pipeline and cluster, one per project and purpose, with only the permissions it needs.
| Docker Hub | Harbor |
|---|---|
| Organisation namespace | Project |
| Team with Read-only access | Directory group as project member, role Guest |
| Team with Read & Write access | Role Developer: push and pull |
| Team with Admin access | Role Maintainer, or Project Admin to manage members |
| Personal access token for a person | CLI secret from the person’s Harbor profile |
| Access token used by a pipeline | Project robot account |
| Automated build | CI job that pushes with a robot account |
| Docker Scout image analysis | Trivy scan on push, and SBOM generation |
| Repository webhook | Project webhook, with a payload of Harbor’s own format |
| Immutable tags | Tag immutability rules |
A project robot account is named robot$<project>+<name> with the default prefix, so quote it in a shell. Its secret is shown once, when it is created, and can be refreshed later but never read again. Robot accounts expire after 30 days by default: set each one’s expiry to match your rotation policy, or a pipeline stops pushing the day its account expires.
Set the project options before images arrive: Automatically scan images on push, Prevent vulnerable images from running with the severity you choose, SBOM generation and a storage quota. Leave tag immutability rules until after the last replication run: an immutable tag cannot be overwritten, by replication either.
Step 3: replicate your repositories from Docker Hub
- Create the endpoint. Under Administration, then Registries, select New Endpoint and the Docker Hub provider. The Access ID is a Docker Hub account and the Access Secret an access token that can read every private repository that moves. Select Test Connection.
- Create the rule. Under Administration, then Replications, select New Replication Rule, choose Pull-based and the Docker Hub endpoint as Source Registry.
- Filter by name and tag. The name filter’s first part is the Docker Hub namespace:
acme/**copies every repository ofacme, and without a namespace Harbor lists every namespace the account can see. The tag filter matches or excludes tags, for example to leave out short-lived branch builds. Harbor’s label filter does not apply, because Docker Hub repositories carry no Harbor labels. - Set the destination. Enter the Harbor project as Destination Namespace. With the default flattening of one level,
acme/apilands as<project>/api. - Choose the trigger. A rule that pulls from Docker Hub runs manually or on a schedule. Event-based triggers react to pushes into Harbor itself, so they do not apply here.
- Decide on override. A tag that already exists in Harbor with a different image is skipped unless Override is on. Turn it on if tags such as
latestmove on Docker Hub during the parallel run.
Each run lists your repositories and their tags through the Docker Hub API and copies each tag’s image, with every platform of a multi-architecture image. Manifests are copied as they are, so digests stay the same and a reference pinned by digest finds the same image in Harbor. A tag whose image is already in Harbor is not copied again, so scheduled runs copy only what is new or changed. The replication rule documentation has the filter syntax.
Docker counts reading a manifest as a pull, and a run reads the manifest of every tag the filters match before it decides to skip one. A multi-architecture image counts once per architecture when it is copied. Docker limits how many pulls anonymous users and free accounts can make. On an account with a limit, keep the filters tight and the schedule sparse, and copy a large estate over several runs.
Signatures need a check. Harbor’s Docker Hub adapter copies tags and nothing else. A Cosign signature stored as a tag of its own, ending in .sig, comes across when the tag filter lets it through; signatures and SBOMs attached to an image without a tag are not listed. Harbor documents signature replication between Harbor instances, not from Docker Hub. Check one signed image after the first run, and plan to sign again in Harbor from your pipelines, where Harbor links each signature to its image and a project can require one before any pull.
Step 4: route public images through a proxy cache
Public base images are not copied. A proxy cache project fetches each one from Docker Hub on first pull, keeps it, and checks Docker Hub for a newer version on later pulls.
- Create a second Docker Hub endpoint for the cache, signed in. Every user who can pull from the proxy cache project can pull anything the endpoint’s account can reach, private repositories included, so use an account that sees public images only. An unauthenticated endpoint pulls under Docker’s anonymous limit, which every build behind Harbor then shares.
- Create the project. Under Projects, select New Project, turn on Proxy Cache and choose the endpoint. Nobody can push to a proxy cache project.
- Change the references. Prefix each public image with the Harbor hostname and the project. Official images live under
libraryon Docker Hub. Harbor adds it to a name without a namespace, but writing it out keeps each reference explicit.
| Reference today | Through Harbor |
|---|---|
nginx, meaning docker.io/library/nginx |
harbor.acme.internal/dockerhub/library/nginx |
docker.io/vendor/agent |
harbor.acme.internal/dockerhub/vendor/agent |
acme/api, your own repository |
harbor.acme.internal/acme/api, replicated |
If Docker Hub cannot be reached, the proxy cache serves the copy it holds; if an image has been removed from Docker Hub, it serves nothing. Harbor gives each new proxy cache project a retention policy of 7 days, so images nobody pulls are removed from the cache. The proxy cache documentation describes each case.
Step 5: move builds, scanning and webhooks
- Automated builds become CI jobs. Docker has deprecated Automated Builds and states that they will be fully retired on 1 April 2027, so this step is due either way. For each repository, copy the build rules, environment variables and test settings from Configure automated builds into a pipeline in GitLab, Forgejo or the CI you already run, which builds the image and pushes it to Harbor with a robot account. Secrets among the build variables go into the CI’s own secret store.
- Scanning. Trivy scans each image on push and on a schedule, and generates an SBOM stored beside the image. Run a scan across the replicated repositories before the cutover, so the first blocked pull is not a surprise on the day.
- Signing. Pipelines sign with Cosign or Notation against the Harbor reference. Once every image in a project is signed, turn on the project’s Cosign or Notation policy so unsigned images cannot be pulled.
- Webhooks. Harbor sends project webhooks on events such as an artifact pushed or a scan completed, in its own JSON format or as CloudEvents. Receivers that parsed Docker Hub’s payload are updated.
Step 6: switch clients, then freeze Docker Hub
Both registries hold the images for a while. Docker Hub stays the source until consumers have moved.
The cutover, in order
- Seed: The scheduled rule keeps Harbor in step with Docker Hub.
- Push to both: Pipelines push each new image to Harbor and to Docker Hub.
- Pull from Harbor: Deployments, charts and compose files switch, environment by environment.
- Stop Docker Hub pushes: A last manual run copies anything pushed outside the pipelines, then the rule is disabled.
- Freeze: Docker Hub repositories stay untouched until a full release cycle has shipped from Harbor.
Credentials change with the references. For Kubernetes, create a pull secret per namespace from a robot account and reference it in imagePullSecrets, or attach it to the namespace’s service account. Every node and build agent must trust the certificate Harbor presents, or Docker and containerd refuse the registry.
# A pipeline signs in with its robot account; the name contains a $ and is quoted
echo "$HARBOR_ROBOT_SECRET" | docker login harbor.acme.internal \
-u 'robot$acme+ci' --password-stdin
# A namespace pulls with its own robot account
kubectl create secret docker-registry harbor-pull -n shop \
--docker-server=harbor.acme.internal \
--docker-username='robot$acme+k8s-shop' --docker-password="$ROBOT_SECRET"
On build agents, replace ~/.docker/config.json entries and credential helpers that point at Docker Hub with ones for Harbor, and keep the Docker Hub sign-in only where something still pulls from it directly. When the freeze ends, deactivate the Docker Hub access tokens the pipelines used, remove the Docker Hub pull secrets from every namespace, and reduce the Docker Hub subscription to what the proxy cache account and any public images still need.
Running Harbor in production
A registry is on the path of every build and every deployment.
- PostgreSQL and object storage. Harbor’s database records which layers make up which tag, and the layers sit in an S3-compatible bucket or on disk. Redis or Valkey queues replication, scans and garbage collection.
- Garbage collection. Deleting a tag frees nothing: the space comes back when garbage collection removes the blobs no manifest references. It can run on a schedule, with a dry run first.
- Retention and quotas. Retention rules keep the newest or the last-pulled tags in each repository and remove the rest; project quotas stop one team filling the bucket.
- The key with the backups. Harbor encrypts the credentials it stores, such as replication endpoint secrets, with a key on disk, so the database, the bucket and that key are backed up as one set.
Pilae operates Harbor this way, on its own PostgreSQL rather than the bundled container. The database, the bucket and the key in /data/secret are backed up daily as one set, encrypted and stored offsite in the country your contract names, and on Enterprise a restore test every month is recorded in the console. Sign-on goes through OIDC from the first day. It runs on your premises or on dedicated machines in Pilae Cloud, answering only on your private network. The Pilae Agent rehearses each upgrade on a copy, waits for your approval and applies it in your window; Harbor does not support downgrades, so the snapshot taken before is the way back.
Let Pilae run the move
Pilae runs Docker Hub to Harbor migrations at a fixed price: the reference inventory, projects, sign-on and robot accounts, replication and the proxy cache, the move of automated builds into your CI, and the switch of every pipeline and cluster. Then we operate Harbor for you under a contract that, from the Business plan, includes a monthly availability commitment with service credits. See migration services for what the fixed price covers, or tell us how your images are built and pulled today and we will scope it.
Questions
Can Harbor copy our images from Docker Hub?
Do we still need a Docker Hub account after the move?
What happens to our Docker Hub automated builds?
Do image signatures come across?
Is Harbor open source?
How long does a Docker Hub to Harbor migration take?
Let us run the move for you
An inventory, a parallel run and a cutover plan, at a fixed price. Then we operate the app.
- Go deeperSaaS migrationA fixed-scope migration off Google Workspace, Microsoft 365, Zapier, Airtable and ChatGPT to open-source apps, with a parallel run and a cutover plan.
- CheckManaged operationsPatching, daily encrypted backups, monitoring and incident response for your open-source apps, under an SLA with an availability commitment of up to 99.9%.
