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.

Start with one workloadThe steps

Written for
The engineer who will do the work
Or run by Pilae
At a fixed price, then operated

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:

  1. 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.
  2. Teams and permissions. Each repository’s Permissions tab shows which teams have Read-only, Read & Write or Admin access.
  3. Tokens. Personal access tokens and organisation access tokens, with their Last used column, show which pipelines and clusters sign in to Docker Hub.
  4. 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.
  5. Credentials on clients. imagePullSecrets in each Kubernetes namespace whose server is https://index.docker.io/v1/, credsStore and credHelpers in ~/.docker/config.json on 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.

  1. 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.
  2. 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.
  3. 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

  1. 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.
  2. Create the rule. Under Administration, then Replications, select New Replication Rule, choose Pull-based and the Docker Hub endpoint as Source Registry.
  3. Filter by name and tag. The name filter’s first part is the Docker Hub namespace: acme/** copies every repository of acme, 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.
  4. Set the destination. Enter the Harbor project as Destination Namespace. With the default flattening of one level, acme/api lands as <project>/api.
  5. 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.
  6. 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 latest move 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.

  1. 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.
  2. Create the project. Under Projects, select New Project, turn on Proxy Cache and choose the endpoint. Nobody can push to a proxy cache project.
  3. Change the references. Prefix each public image with the Harbor hostname and the project. Official images live under library on 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

  1. Seed: The scheduled rule keeps Harbor in step with Docker Hub.
  2. Push to both: Pipelines push each new image to Harbor and to Docker Hub.
  3. Pull from Harbor: Deployments, charts and compose files switch, environment by environment.
  4. Stop Docker Hub pushes: A last manual run copies anything pushed outside the pipelines, then the rule is disabled.
  5. 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?

Yes. A pull-based replication rule with a Docker Hub endpoint copies your repositories, filtered by name and tag, manually or on a schedule. Each tag comes across with its image, multi-architecture images with every platform, and the manifests are copied unchanged, so digests stay the same. Teams, access tokens, automated builds and Docker Scout results do not come across.

Do we still need a Docker Hub account after the move?

For public base images, yes. Harbor keeps fetching them from Docker Hub through a proxy cache project, and that project should sign in. Docker limits how many pulls anonymous users and free accounts can make, and without a sign-in every build behind Harbor shares one anonymous limit. Signed in with a paid account's token, the cache fetches each image again only when it changes, and checks for newer versions with requests Docker does not count.

What happens to our Docker Hub automated builds?

They move into your CI. Harbor stores images and does not build them. Docker has deprecated Automated Builds itself and states that they will be fully retired on 1 April 2027. Each build rule becomes a pipeline job that builds the image and pushes it to Harbor with a robot account.

Do image signatures come across?

Not reliably. The Docker Hub adapter copies tags, so a Cosign signature stored as a tag of its own comes across when the tag filter lets it through, while signatures and SBOMs attached without a tag are not listed. Harbor documents signature replication between Harbor instances, not from Docker Hub. The dependable route is to sign images again in Harbor from your pipelines.

Is Harbor open source?

Yes. Harbor is Apache-2.0 and a graduated project of the Cloud Native Computing Foundation. There is no paid edition and no enterprise build: scanning, signing, replication, proxy caching and OIDC sign-on are all in the release Pilae deploys.

How long does a Docker Hub to Harbor migration take?

It depends on how many places name an image and how many pipelines push one, not on the number of images: replication copies tags in the background, while every Dockerfile, chart and pipeline is changed and tested. The inventory in step 1 settles the scope, and Pilae quotes the move at a fixed price once it is done.

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.

Start with one workload

  • 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%.