Migrate from JFrog Artifactory to Harbor

A practical plan for moving Docker and Helm content from Artifactory to self-hosted Harbor, including what moves cleanly, what needs rework, and how to cut over without breaking pulls.

On this page

Migrate from JFrog Artifactory to Harbor: what the move involves

If your team keeps Docker images and Helm charts in Artifactory and is facing a renewal, a pricing change or a data residency requirement, Harbor can take over that content through replication rules and proxy cache projects. Non-container packages such as Maven, npm or Python need a separate path, so plan that work alongside the container move rather than assuming Harbor covers it. The move is usually run by platform and security engineers working with the owners of the CI pipelines and the clusters that pull images, because those are the parties whose credentials and configuration change at cutover.

Harbor can register JFrog Artifactory as a replication endpoint, and a pull-based replication rule copies repositories, tags and labels from Artifactory into a Harbor project on a manual, scheduled or event trigger. Proxy cache projects that point at Artifactory let Harbor serve images on demand while repositories are still moving, so consumers keep working during the transition. Confirm the adapter behavior for each OCI media type you use, since Harbor v2.15.0 added OCI type support to its JFrog registry adapter and older releases may not handle every artifact in your estate. Check the replication endpoint documentation in the Harbor docs before you build rules.

Effort and risk depend on three things: how many repositories and projects you hold, how tightly CI jobs and deployment scripts are coupled to Artifactory hostnames and access tokens, and how Kubernetes clusters reference image pull secrets. Inventory each of these before scheduling anything, and ask your Harbor implementation partner to put the repository count, CI owners and cluster list into a written scope. Keep Artifactory running until every pipeline and cluster has pulled from Harbor successfully, and take a backup of the Harbor database before any upgrade, as the v2.15.2 release notes advise.

Which Artifactory capabilities map to Harbor, and which need rework

This table maps the Artifactory capabilities that matter for a Harbor move to their Harbor equivalents and marks each as clean, needs rework or gap. Read it as a scope check: Harbor covers OCI content only, so anything outside Docker images and Helm charts needs a separate platform such as Pulp. Confirm each rework item in a proof of concept before cutover.

Artifactory capabilityHarbor equivalentStatus
Docker and Helm repositoriesHarbor projects store images and Helm charts as OCI artifacts, and Helm charts are pushed and pulled with oci:// referencesClean
Remote repositories for Docker Hub and other registriesProxy cache projects for Docker Hub and JFrog Artifactory upstreams, read-only for pushes, serving cached copies if the upstream is unreachableNeeds rework
Remote Maven, npm, PyPI and other package repositoriesNone in Harbor, since it handles OCI content only; move these to Pulp remotesGap
Replication between registriesPull-based or push-based replication rules with Artifactory as an endpoint, filtered by repository, tag and labelClean
Federated repositories across JFrog sitesNo direct equivalent; plan separate Harbor instances and replication rules between themGap
RBAC and SSOProject-level role-based access control with LDAP/AD and OIDC single sign-on; group mapping must be rebuiltNeeds rework
Vulnerability scanning (Xray)Trivy scanning enabled at install with --with-trivy or an external Trivy instance; no Xray curation or license policiesNeeds rework
Xray curation and policy blockingNo direct open-source match in Harbor; document the policy gap and decide on alternativesGap
Garbage collectionHarbor provides garbage collection for unreferenced blobs, scheduled by the administratorClean
Audit logsHarbor records audit logs for project activity; confirm retention and export against your log platformNeeds rework
REST APIHarbor REST API with embedded Swagger UI; scripts and CI calls against Artifactory endpoints must be rewrittenNeeds rework

What data and integrations move, and what to rebuild

Image and chart content moves through Harbor replication pulls, while projects, identities, CI credentials, pull secrets, webhooks and retention rules must be rebuilt by hand. Treat the two halves as separate workstreams with separate checks. The cards below separate what Harbor can copy from what your teams must reconfigure.

Image and chart content

Harbor can pull container images and Helm charts from Artifactory through a replication endpoint, using pull-based rules filtered by repository, tag and label. Harbor stores charts as OCI artifacts, so Helm charts ride the same replication path as images. Confirm that the Artifactory repositories you plan to move are Docker or Helm repositories, because Harbor does not handle the other package types. Check that tag and digest counts match after each run.

Project and repository layout

Artifactory repository keys do not map one to one onto Harbor projects, so decide the target layout before creating rules. A Harbor project carries its own access control, retention and scanning settings, and repository names inside it may need renaming to match your naming scheme. Write the mapping down as a table, and review it with the teams that own each image path.

Users, groups and RBAC

Harbor does not import Artifactory users or permissions. Map each Artifactory group to a Harbor project role, and connect identities through LDAP, AD or OIDC single sign-on if your directory is the source of truth. Confirm which service accounts need push rights and which need pull only, and remove permissions that were granted by default in Artifactory.

CI credentials and robot accounts

Every pipeline that pushes or pulls through Artifactory holds a credential that must be replaced with a Harbor credential scoped to the right project. Inventory pipeline variables, secret stores and build agents before cutover, since a missed credential fails only when that pipeline next runs. Rotate the old credentials after the last pipeline has moved.

Kubernetes image pull secrets

Each namespace that pulls from Artifactory holds an image pull secret, and workloads that reference it will keep failing until the secret points at Harbor. Plan a rollout by namespace, and update Helm values or manifests that hard-code the registry hostname. Keep the Artifactory secret in place until all deployments have restarted on Harbor image references.

Webhooks, scanning and retention

Artifactory webhooks, cleanup jobs and tag retention scripts do not transfer, so review each one and recreate it in Harbor's own tools. Harbor v2.15.3 blocks webhooks to internal network addresses by default, so confirm any receiver endpoints before go-live. Harbor proxy cache projects get a default 7-day retention policy, so set explicit retention for any project you intend to keep.

Artifactory export limits

Artifactory's own export is restricted for JFrog Cloud customers, so do not assume a full backup of Artifactory state exists. Pull content through the Docker registry API and the JFrog CLI, and document what each export does and does not capture. The separate export page covers the methods, the metadata that can and cannot be recovered, and the steps for self-managed deployments.

Migration sequence from inventory to decommission

This sequence moves Docker and Helm content from Artifactory into Harbor in controlled stages, so each repository is verified before any client changes. It ends with Artifactory read-only and then decommissioned, with a rollback path kept until the last step is signed off.

  1. Inventory repositories, tags and charts

    Your platform team lists every Docker and Helm repository in Artifactory, with its tags, digests, Helm chart versions, retention rules and the CI jobs and clusters that pull from each one. Record which images are referenced by digest and which by mutable tag, because that decides how far a copy can be verified. The output is a repository inventory with owners, consumers and a migration priority for each entry. The step is done when every consumer of every repository appears in the inventory and the owners have signed off.

  2. Run a pilot with one replication rule

    Register Artifactory as a replication endpoint in Harbor, then create one pull-based rule for a single low-risk repository, filtering by repository name and tag. Trigger it manually first, then check the run history for failed or skipped artifacts. The output is a replication report for the pilot and a short list of any filter or credential issues found. The step is done when the copied images and charts match the source digests and Helm charts install from the Harbor OCI path in a test cluster.

  3. Scale replication across the inventory

    Extend the replication rules to the remaining repositories in priority order, using scheduled or event triggers only where the owners need continuous sync and a bandwidth limit where the link is shared. Confirm that the Artifactory user or token behind the endpoint has read access to every repository in scope. The output is a per-repository replication report with digest comparisons and a list of artifacts that failed to copy, each with an owner. The step is done when the failed list is empty or each gap has an agreed fix.

  4. Parallel run with proxy cache projects

    Create Harbor proxy cache projects that point at Artifactory as the upstream, so clients can pull through Harbor while content is still served from Artifactory. Move one non-production cluster or CI pipeline to the Harbor endpoint first, and keep the original Artifactory path available for rollback. Check the cache retention policy, which defaults to 7 days, so cached copies do not expire during testing. The output is a pull log showing which workloads read from Harbor and any authentication or timeout errors. The step is done when the test workloads have run through a full build and deploy cycle without fallback.

  5. Repoint CI credentials and pull secrets

    Create Harbor robot accounts with the narrowest project permissions each pipeline needs, then update CI variables and Kubernetes image pull secrets in each cluster, one environment at a time. Start with lower environments and keep the old Artifactory secret in place until the new one has pulled successfully. The output is a list of pull secrets updated per cluster, a list of CI variables changed per pipeline, and the revocation date for each old credential. The step is done when no workload still references an Artifactory registry host in its manifests or pipeline definitions.

  6. Cut over and hold Artifactory read-only

    Schedule the production cutover with the application owners, freeze new pushes to Artifactory, run a final replication for the delta, and verify digests for every production image and chart. Then set Artifactory repositories to read-only for a defined hold period agreed with the owners, so a rollback is still possible. Keep the rollback runbook current, listing the exact credential, endpoint and replication steps to restore the previous path. The output is a signed cutover record and the rollback runbook. The step is done when production pulls and pushes succeed through Harbor and no alerts fire during the hold period.

  7. Decommission Artifactory after sign-off

    After the read-only hold ends without rollback, export the final metadata and retain the audit evidence your compliance team requires, including the replication reports and the cutover record. Then remove the Artifactory replication endpoints, revoke remaining tokens, and shut down or cancel the subscription once your contract terms allow. Ask your JFrog account team to confirm the exit terms and any data retention commitments in writing before you cancel. The output is a decommission record listing revoked credentials, retained evidence and the final date of Artifactory access. The step is done when the evidence package is stored outside Artifactory and the owners accept the record.

How replication and proxy cache projects work together during cutover

Replication and proxy cache projects do different jobs during a cutover, and you need both. Pull-based replication rules copy artifacts from Artifactory into a Harbor project. Each rule can filter by repository name, tag, label and resource type, so you can move one repository at a time instead of the whole instance. Rules run manually, on a cron schedule, or on push and retag events, and each task can carry an optional bandwidth limit so that copying does not saturate the links your build agents use. Start with a manual run for one low-risk repository, confirm the tag count and digests match on both sides, and only then schedule the rest.

A proxy cache project pointed at Artifactory is the safety net while those copies are still in progress. Harbor fetches images from Artifactory on demand, caches them, and serves the cached copy if the upstream becomes unreachable. Proxy cache projects are read-only for pushes, so teams cannot write new content into the cache by accident. Cached content gets a default 7-day retention policy, which is short enough to matter during a migration. Review that retention setting before cutover, because a cache that expires during a long move will send pulls back to Artifactory.

Harbor's documentation says its proxy cache checks cached images with HEAD requests, which do not count against Docker Hub's rate limiter. Confirm in your Harbor version whether the same check runs for JFrog Artifactory upstreams and how often it revalidates, since that determines how quickly a re-pushed tag in Artifactory reaches consumers. Also confirm how the cache behaves for multi-architecture manifests and Helm charts before you rely on it. Test a pull through the cache from a build agent and from a cluster node, and record the results so the cutover has a documented baseline.

How the migration differs by estate size and starting point

A small estate usually has a handful of Docker repositories, a Helm chart repository and one Kubernetes cluster. In this case the migration is mostly a single replication pass followed by a short cutover, and the main question is whether the team can afford a brief window where both registries serve the same images. Harbor's proxy cache projects let you point the new registry at Artifactory on demand, so the cluster can keep pulling while you copy the rest.

  • Fewer rules to write: one or two pull-based replication rules with repository and tag filters usually cover the whole inventory.
  • Single pull secret set: the image pull secrets in one namespace or a small number of namespaces are easy to find and rotate.
  • Simple CI wiring: a few pipelines push and pull, so repointing them by hand is practical.
  • Charts as OCI: confirm that your Helm clients use oci:// references, because Harbor serves charts as OCI artifacts and no longer bundles ChartMuseum.

Before cutover, confirm the image count and tag list in each repository against Harbor so nothing is skipped by the filters.",

What drives cost and duration, and how to reduce each

This table lists the drivers that change the effort of moving Docker and Helm content from Artifactory to Harbor and the cost of running Harbor afterward. Read each row for what to measure in your estate, which part is one-time and which recurs, and what to ask for in a written scope.

DriverWhy it changes cost or effortHow to keep it down
Repository and tag countEach Docker and Helm repository needs a mapped Harbor project, replication rule or proxy cache project, and each tag set adds replication time and verification work.Inventory repositories and tags with the JFrog CLI or REST API first, then consolidate stale tags before the first replication run.
Total artifact size and transfer bandwidthInitial replication copies every selected image and chart, and storage sizing for Harbor depends on the same totals. Bandwidth between Artifactory and Harbor sets how long the first pass runs.Filter rules by repository and label, use the per-task bandwidth limit, and schedule the bulk copy outside peak build hours.
CI pipelines holding Artifactory credentialsEvery pipeline that pushes or pulls images needs a new robot or user credential and a repointed registry hostname, so the count sets the testing and cutover workload.Build a list of pipelines from source control, group them by owner, and move low-risk pipelines first.
Kubernetes clusters with image pull secretsEach cluster holds a pull secret for the Artifactory hostname, and each secret must be replaced and rolled out in every namespace that uses it.Script secret creation per namespace, roll out in one cluster at a time, and keep the Artifactory endpoint live until pulls are confirmed.
Xray or curation that must be replacedXray policies, curation rules and license checks have no direct Harbor equivalent. Harbor provides Trivy scanning, so policy gates must be rebuilt in CI or another tool.List every active Xray policy and curation rule before scoping, then decide which controls move to Trivy findings and which need another product.
SSO and RBAC mappingArtifactory groups and permissions must map to Harbor projects, roles and OIDC or LDAP/AD groups, and mismatches leave pipelines unable to push or pull.Export current permission targets, map each to a Harbor project role, and test service accounts before disabling old access.
HA design with PostgreSQL and ValkeyHarbor's bundled database and cache affect availability design, backup scope and the number of components the team operates. Harbor v2.15.2 moved the internal database to PostgreSQL 18 and replaced Redis with Valkey.Decide between the bundled components and external managed or self-run PostgreSQL and Valkey, and document backup and restore for each before cutover.
Harbor upgrade disciplineHarbor 2.15.2 and 2.15.3 included a database upgrade and breaking webhook and content trust changes. Each minor release adds regression testing and a backup step.Pin a supported version, take a backup before every upgrade, and test replication, scanning and pulls in staging first.
One-time workMigration design, replication and proxy cache setup, CI credential changes, pull secret rollout, and parallel-run testing happen once, though the scope depends on the drivers above.Ask the provider to fix the scope in writing, including the repositories, pipelines and clusters in each phase.
Recurring workHarbor hosting, object storage, database and cache operations, patching, version upgrades and Trivy scanning continue after cutover, and their cost follows storage growth and scan volume.Set retention and garbage collection schedules, budget a recurring upgrade window, and ask for run costs by component in the quote.

What usually goes wrong in a Harbor cutover and how to prevent it

A Harbor cutover from Artifactory usually fails at the edges: tags that never replicated, credentials and hostnames still pointing at the old registry, and Harbor settings that changed between releases. Each card below names one failure and the check that prevents it before traffic moves.

Unpulled or unmapped tags

Replication rules filter by repository name, tag, label and resource type, so a rule that looks complete can skip tags that were never matched. Artifactory repositories often hold tags that no pipeline pulls, along with older release tags that a rollback may need. Before cutover, compare the tag list per repository in Artifactory with the list in the Harbor project, and confirm that every tag a deployment references exists in Harbor by digest, not only by name.

Pull secrets still pointing at Artifactory

Kubernetes image pull secrets store the registry hostname and credentials for each namespace. If a secret still names the Artifactory host after cutover, workloads that restart or scale may pull from the old registry, or fail once Artifactory is retired. Inventory every imagePullSecrets reference across namespaces, service accounts and Helm values, then create Harbor robot accounts with pull-only scope and roll the secrets namespace by namespace while the proxy cache still serves the old path.

CI jobs with hardcoded hostnames

Pipelines often hardcode the Artifactory hostname in build scripts, Dockerfiles, Helm chart dependencies and oci:// references. These references fail silently when they point at a host that no longer receives pushes. Search the source repositories and pipeline variables for the old hostname, move the value into a single CI variable per environment, and push a test build from each pipeline to a Harbor project before retiring the old credentials.

Webhooks blocked by the v2.15.3 default

Harbor v2.15.3 blocks webhooks to internal network addresses by default, according to its release notes. Notification webhooks that post to CI systems, chat tools or internal scanners on private addresses will stop delivering after an upgrade to that release unless an administrator changes the setting. Before upgrading, list each webhook target and its address, decide which targets are internal and approved, and test delivery in a staging instance so a failed build trigger does not go unnoticed.

Content trust signing failures

Harbor v2.15.3 also fails signing of unsigned images in projects that enforce content trust. A replication or CI step that signs artifacts after pull may now error, and a project that enforces trust can reject images that were copied in unsigned. Identify which Harbor projects enforce content trust, confirm that replicated images arrive with their existing signatures, and run a copy into one enforcing project in staging before changing any production rule.

Database and cache changes in v2.15.2

Harbor v2.15.2 upgrades the bundled internal database from PostgreSQL 15 to PostgreSQL 18 on container startup and replaces Redis with Valkey as the cache backend. The release notes recommend a backup before upgrading and a reindexdb run if index problems appear. Take a verified database backup, record the current version, run the upgrade in staging, and keep the reindexdb step ready in the runbook. If you use an external database, confirm its version support with your database team, since the bundled upgrade may not apply to it.

Retention and garbage collection removing content

Proxy cache projects get a default 7-day retention policy, and garbage collection deletes blobs that no manifest references. An image copied during cutover that is not tagged, or a cached image that expires, can disappear before a deployment or rollback needs it. Set retention rules per project before cutover, exclude release and base image repositories, and schedule garbage collection only after confirming that every production digest exists in a non-cache project.

Questions teams ask before moving Artifactory containers to Harbor

How long does a move from Artifactory to Harbor take?

The duration depends on the number of repositories, the total image and chart volume, how many CI pipelines and clusters pull from them, and how many change windows the organization allows. Replication itself is rarely the slow part. The slow parts are inventorying which images are actually in use, updating credentials in every pipeline and cluster, and verifying that workloads pull successfully from Harbor before Artifactory is retired. Ask any provider for a written plan that lists these steps separately, and confirm the assumptions behind each one against your own estate, since no general figure applies to every environment.

Can our own team migrate Artifactory containers to Harbor without outside help?

A small estate with a few Docker and Helm repositories can often be moved by a team that already runs Kubernetes and operates Harbor. The work is mostly configuration: registering Artifactory as a replication endpoint, creating pull-based rules, and pointing proxy cache projects at Artifactory during cutover. The caveats are CI and pull secrets. Every pipeline that pushes or pulls, every imagePullSecrets entry and every Helm values file that references a registry hostname has to change, and missing one causes failed deployments. Teams with many clusters or unclear ownership of pipelines usually benefit from a written, fixed-scope plan.

What do we need to provide before a migration starts?

You need read access to Artifactory so the repositories, tags and labels in scope can be listed, plus administrator access to the target Harbor instance and its projects. Equally important are the named owners of each CI pipeline and cluster, because they must approve credential changes. Plan for change windows that cover cutover and rollback, and agree on a freeze for image pushes during the final sync. Also confirm who maintains the Harbor installation after handover, since upgrades in the 2.15 line include breaking changes that need review.

Do JFrog Xray and federation have direct equivalents in Harbor?

No. Harbor provides vulnerability scanning through Trivy, enabled with the --with-trivy install option or an external Trivy instance, which covers image scanning but is not a drop-in replacement for Xray's policies, watches and wider component analysis. Harbor replication is push or pull based between registries, which is not the same as Artifactory federation between instances. Teams that depend on Xray policies, curation or federated topologies should document those dependencies and plan how to replace or accept them before cutover. A separate page covers the scanning gap in detail.

What should a quote for this migration include?

A quote should follow from a written scope and list each deliverable: an inventory of repositories and images in use, the Harbor deployment or upgrade, replication and proxy cache configuration, updates to CI credentials and Kubernetes pull secrets, cutover and rollback steps, verification, backup procedures and handover documentation. It should name what the client provides, what is excluded (for example, Xray replacement or non-container package formats), and how changes to scope are handled. DeployOpen does not publish a price list, so ask for the quote in these terms and compare line items rather than totals.

What recurring costs remain after Harbor is running?

Recurring costs are the infrastructure that hosts Harbor, including compute, the PostgreSQL database, cache, and storage for images and their backups, plus the staff time for patching, upgrades and monitoring. Harbor itself is licensed under Apache-2.0, so there is no per-server or per-component subscription. Costs rise with image volume, replication frequency and high availability requirements. Ask any provider to separate one-time migration work from ongoing support, and to state whether upgrades such as the move to PostgreSQL 18 in v2.15.2 are included in a retainer or priced separately.

Will Helm charts and images keep working after the move?

They should, as long as the chart and image references are updated. Harbor stores Helm charts as OCI artifacts, and since v2.8.0 it no longer includes ChartMuseum, so charts are pulled with oci:// references. Charts that still point to a classic chart repository URL must be changed. Test each chart with helm pull and a deployment in a non-production cluster before cutover, and confirm that signature or SBOM artifacts that rely on the referrers API are copied as well.

How DeployOpen scopes and runs an Artifactory to Harbor migration

DeployOpen is a Chainscore Labs company that plans, implements, integrates, hardens, backs up, documents and supports self-hosted open-source platforms inside the client's own infrastructure, whether that is their cloud accounts, data centers or an air-gapped network. For an Artifactory to Harbor move, that means the Harbor deployment, its database and storage, the replication endpoints that point at Artifactory, the proxy cache projects used during cutover, and the runbooks your platform team will use after handover. Most engagements are fixed-scope, so the first useful step is a written inventory: which Docker and Helm repositories exist, which are local versus remote, who pulls from them, and which CI jobs and Kubernetes clusters hold credentials. That inventory drives the scope, the deliverables and the timeline, all agreed in writing before work starts.

There is no published DeployOpen price list. A quote follows from the written scope, so the inputs that move the number are the repository count, total image and chart volume, the number of CI pipelines and clusters to repoint, whether Harbor will run highly available (see the Harbor high availability Helm guide), and how much testing and parallel running the business requires. Ask any provider, including DeployOpen, to separate one-time work (design, installation, migration, hardening, evidence collection) from recurring work (patching Harbor, upgrading between minor lines, backups, monitoring and on-call). Ask for the assumptions behind each line. Ongoing support, upgrades and continuous testing are available as retainers, and they can be scoped separately from the migration itself.

Before signing, confirm three points in writing with whichever partner you choose. First, the assumed Harbor version and the upgrade path, since recent releases changed the bundled database, cache and webhook behavior and their release notes recommend a backup first. Second, who owns the cutover decision and the rollback plan. Third, what evidence you will receive for your own compliance team, such as configuration records, access reviews and backup test results. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications. Those come from independent auditors and certification bodies that your organization selects.

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.