> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/get-started/migrate-to-harness-artifacts/from-jfrog-artifactory.md).

# Migrate from JFrog Artifactory

Move artifacts from JFrog Artifactory to Harness Artifacts using the Harness CLI migration tool, with a concept mapping and key configuration steps.

JFrog Artifactory and Harness Artifacts share the same fundamental model: repositories (or registries) that hold multiple package formats, remote sources for pulling upstream dependencies, and scanning to catch vulnerable packages before they reach production. The concepts you already know carry over directly; the names and a few workflows change.

This guide walks you through two migration strategies and the specific configuration you need for a JFrog source.

## Compatibility, changes, and improvements

**What stays the same**. Both systems support the same broad range of package formats: Docker, Helm, Maven, npm, PyPI, NuGet, Go, Cargo, Debian, Alpine, RPM, and more. Your artifact structure, version history, and metadata all migrate intact. The packages your pipelines consume today will be available at a new URL after migration.

**What changes for your team**.

| JFrog concept                 | Harness Artifacts equivalent                              | Notes                                                          |
| ----------------------------- | --------------------------------------------------------- | -------------------------------------------------------------- |
| Local repository              | Registry                                                  | One registry per package type                                  |
| Remote repository             | Upstream proxy                                            | Configured separately, then attached to a registry             |
| Virtual repository            | Registry with upstream proxies                            | Set priority order in the registry settings                    |
| Xray scan result              | Vulnerability scan result                                 | Scanning is built in, not a separate product                   |
| JFrog Curation                | Dependency Firewall                                       | Uses OPA policies shared with the rest of the Harness Platform |
| Access Token / Identity Token | Personal access token (PAT) or Service access token (SAT) | JFrog API keys are deprecated since Artifactory 7.4x           |
| `<name>.jfrog.io` endpoint    | `pkg.harness.io`                                          | One global endpoint, no region routing                         |

**What improves**. In JFrog, scanning (Xray), curation (JFrog Curation), and distribution are separate licensed products layered on top of Artifactory. In Harness, vulnerability scanning and the Dependency Firewall are part of the same registry product and governed by the same OPA policies that control your CI and CD pipelines. Signing keys for Debian, Alpine, and Wolfi packages are also built in.

**Software Delivery Agent**. Once your artifacts are in Harness Artifacts, the Harness Software Delivery Agent can query registries, artifact versions, and scan results through the Artifacts REST API (the same API your pipelines use). You can ask the agent questions like "which version of this image last passed a clean scan?" or "what lifecycle rules are set on this registry?" without leaving your delivery workflow. Go to [Using Artifacts with AI agents](https://developer.harness.io/artifact-registry/3.0/agents/using-ar-with-ai-agents.md) for the full picture.

## Before you begin

* Install the [Harness CLI (`hc`)](https://developer.harness.io/artifact-registry/3.0/reference/cli.md) and authenticate to your Harness account. Use the latest version.
* Create a JFrog Access Token or Identity Token. Do not use a JFrog API key; these are deprecated in Artifactory 7.4x and later.
* Know your Artifactory base URL:
  * JFrog Cloud: `https://<name>.jfrog.io/artifactory`
  * Self-hosted: the base URL for your instance, commonly `https://<host>/artifactory`. Confirm the exact path with your Artifactory administrator, as the context root varies by deployment.
* Create the destination registries in Harness Artifacts before running the migration. Go to [Create a registry](https://developer.harness.io/artifact-registry/3.0/registries/create-a-registry.md) for each registry type you are migrating.
* Have push permissions on the Harness destination registries and read permissions on the JFrog source repositories.

## Migration options

You have two approaches. Choose based on how you want to cut over.

**Option A: Gradual cut-over with an upstream proxy**. Point a Harness upstream proxy at your JFrog instance. Packages that do not yet exist in Harness are fetched through the proxy on first request and then cached. You migrate traffic incrementally by updating pipelines one by one. Go to [Create an upstream proxy](https://developer.harness.io/artifact-registry/3.0/registries/create-an-upstream-proxy.md), select **Custom** as the source type, enter your JFrog repository URL in the **Remote registry URL** field, and add your JFrog credentials.

**Option B: Bulk copy with the Harness CLI**. Copy all artifacts in one operation using `hc registry migrate`. This is the approach described in the rest of this guide.

## Bulk migration with the Harness CLI

### Step 1: Create target registries in Harness

Create a Harness registry for each JFrog repository you intend to migrate. The registry type must match the artifact type (for example, a Docker registry for a Docker repository). Note the registry identifier for each; you use it in the migration configuration.

### Step 2: Create the migration configuration file

Create a YAML file that defines the source (your JFrog instance), the destination (Harness Artifacts), and the repository mappings.

{% hint style="info" %}
Both source and destination endpoints must use HTTPS. The Harness destination endpoint is always `https://pkg.harness.io`.
{% endhint %}

{% code title="migration-config.yaml" overflow="wrap" %}

```yaml
version: 1.0.0
concurrency: 5       # packages migrated concurrently
overwrite: false     # set to true to overwrite existing artifacts

source:
  endpoint: https://<name>.jfrog.io/artifactory   # JFrog Cloud or self-hosted base URL
  type: JFROG
  credentials:
    username: ${JFROG_USER}                         # use env vars for credentials
    password: ${JFROG_TOKEN}                        # Access Token or Identity Token
  insecure: false    # set to true for self-signed certificates only

destination:
  endpoint: https://pkg.harness.io
  type: HAR
  credentials:
    username: ${HARNESS_USER}
    password: ${HARNESS_TOKEN}                      # Harness PAT

mappings:
  - artifactType: DOCKER
    sourceRegistry: docker-local                    # JFrog repository name
    destinationRegistry: my-docker-registry         # Harness registry identifier

  - artifactType: HELM
    sourceRegistry: helm-oci-local
    destinationRegistry: my-helm-registry

  - artifactType: HELM_LEGACY                       # non-OCI Helm; converted to OCI automatically
    sourceRegistry: helm-legacy-local
    destinationRegistry: my-helm-registry

  - artifactType: MAVEN
    sourceRegistry: maven-releases
    destinationRegistry: my-maven-registry

  - artifactType: NPM
    sourceRegistry: npm-local
    destinationRegistry: my-npm-registry

  - artifactType: PYTHON
    sourceRegistry: pypi-local
    destinationRegistry: my-pypi-registry
```

{% endcode %}

**Supported artifact types**

| Type          | Description                                                       |
| ------------- | ----------------------------------------------------------------- |
| `DOCKER`      | Docker container images                                           |
| `HELM`        | OCI-compliant Helm charts                                         |
| `HELM_LEGACY` | Non-OCI Helm repositories (converted to OCI format automatically) |
| `MAVEN`       | Maven artifacts                                                   |
| `NPM`         | npm packages                                                      |
| `PYTHON`      | Python / PyPI packages                                            |
| `NUGET`       | NuGet packages                                                    |
| `GO`          | Go modules                                                        |
| `CARGO`       | Cargo (Rust) packages                                             |
| `GENERIC`     | Generic artifacts and files                                       |
| `RPM`         | RPM packages                                                      |
| `ALPINE`      | Alpine APK packages                                               |
| `WOLFI`       | Wolfi APK packages                                                |
| `CONDA`       | Conda packages                                                    |
| `COMPOSER`    | PHP Composer packages                                             |
| `SWIFT`       | Swift packages                                                    |
| `TERRAFORM`   | Terraform modules and providers                                   |
| `CRAN`        | R packages (CRAN format)                                          |
| `RUBY`        | RubyGems packages                                                 |

{% hint style="warning" %}
**Helm chart clients after migration**

Artifacts migrated with `HELM_LEGACY` are stored as OCI-compliant Helm charts in Harness. After migration, update your Helm clients from `helm repo add` syntax to OCI pull syntax: `helm pull oci://pkg.harness.io/<ACCOUNT>/<REGISTRY>/<chart>`. Go to [Helm OCI client setup](https://developer.harness.io/artifact-registry/3.0/setup/helm-oci.md) for the updated configuration.
{% endhint %}

### Step 3: Set your credentials as environment variables

Store credentials in environment variables rather than hard-coding them in the config file.

```bash
export JFROG_USER=your-jfrog-username
export JFROG_TOKEN=your-jfrog-access-token
export HARNESS_USER=your-harness-email
export HARNESS_TOKEN=your-harness-pat
```

### Step 4: Run a dry-run first

A dry run generates a report of what would be migrated without uploading anything. Use it to confirm mappings and catch configuration errors before moving data.

```bash
hc registry migrate --config migration-config.yaml --dry-run --verbose
```

Review the output for any unmapped or skipped repositories before proceeding.

### Step 5: Run the migration

```bash
hc registry migrate --config migration-config.yaml --verbose
```

For large repositories, increase concurrency after confirming the dry-run looks correct:

```bash
hc registry migrate --config migration-config.yaml --concurrency 10 --verbose
```

**Available flags**

| Flag            | Description                                               | Default       |
| --------------- | --------------------------------------------------------- | ------------- |
| `-c, --config`  | Path to configuration file                                | `config.yaml` |
| `--concurrency` | Number of concurrent upload operations                    | `1`           |
| `--dry-run`     | Preview what would be migrated without uploading          | `false`       |
| `--overwrite`   | Overwrite artifacts that already exist in the destination | `false`       |
| `-v, --verbose` | Enable verbose logging                                    | `false`       |

### Step 6: Verify the migration

Confirm that your artifacts arrived in Harness Artifacts before switching any traffic:

1. In the navigation menu, select **Registries**, then select a destination registry.
2. Go to the **Packages** tab and confirm the expected artifact names and versions are listed.
3. Pull one artifact through the Harness registry to confirm it resolves correctly:

```bash
# Docker example: replace with the appropriate client for your format
docker pull pkg.harness.io/<HARNESS_ACCOUNT_ID>/<REGISTRY>/<IMAGE>:<TAG>
```

4. Check that the artifact version and digest match what you migrated from JFrog. If anything is missing, re-run `hc registry migrate` with `--verbose` to identify skipped or failed artifacts.

## Update your clients and pipelines

After the migration is complete, update your clients to point at Harness Artifacts. Go to the relevant client setup page for your package type:

* [Docker](https://developer.harness.io/artifact-registry/3.0/setup/docker.md)
* [Helm OCI](https://developer.harness.io/artifact-registry/3.0/setup/helm-oci.md)
* [Maven](https://developer.harness.io/artifact-registry/3.0/setup/maven.md)
* [npm](https://developer.harness.io/artifact-registry/3.0/setup/npm.md)
* [Python / PyPI](https://developer.harness.io/artifact-registry/3.0/setup/python-pypi.md)

For your CI pipelines, update the registry endpoint and replace JFrog credentials with your Harness token. Go to [Harness CI integration](https://developer.harness.io/artifact-registry/3.0/platform-integrations/harness-ci.md) for configuration examples.

## Troubleshooting

<details>

<summary>Authentication errors: 401 from the JFrog source</summary>

Confirm that you are using a JFrog Access Token or Identity Token, not a user password. JFrog API keys are deprecated in Artifactory 7.4x and later. Verify that the token has read access to the source repositories.

</details>

<details>

<summary>Authentication errors: 401 from Harness Artifacts</summary>

Confirm that the Harness PAT you are using has push permission on the destination registries. Go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md) to check role assignments.

</details>

<details>

<summary>Connection failure to self-hosted Artifactory</summary>

Confirm the source endpoint URL is correct and uses HTTPS. For self-hosted instances with self-signed certificates, set `insecure: true` in the source block. Use this setting only in controlled environments. Do not use it in production pipelines.

</details>

<details>

<summary>Helm charts are not pulling correctly after migration</summary>

Artifacts migrated from a non-OCI Helm repository (`HELM_LEGACY`) are stored as OCI charts. Update your Helm clients from `helm repo add` to OCI syntax. Go to [Helm OCI client setup](https://developer.harness.io/artifact-registry/3.0/setup/helm-oci.md) for the full configuration.

</details>

<details>

<summary>Missing artifacts after migration</summary>

Run the migration again with `--verbose` to review per-artifact logs. Confirm that the source repository name in the mapping matches the exact repository identifier in JFrog (case-sensitive). Confirm that the destination registry exists in Harness before re-running.

</details>

For further help, run `hc registry migrate --help` or contact Harness Support.

{% @harness-feedback/feedback %}
