Migrate Push Replication to Unidirectional Federation

Migrate local repositories that use push replication to unidirectional Federation across two JFrog Platform Deployments (JPDs). The migration tool converts each repository on the source and target JPDs to Federated, removes the legacy replication configuration, and configures the target member in receiving-only mode so artifacts flow from source to target only.

This topic covers the following tasks:

• Prerequisites
• Install the Migration Plugin
• Prepare the Repository List
• Run the Migration
• Review the Results Report
• Verify Federation Health

Who can perform this task: Platform Administrators

Prerequisites

Before you run the migration, confirm the following:

• Artifactory Federation Service (RTFS) is installed and connected on the source and target JPDs. See Artifactory Federation Service (RTFS).
• Trust between JPDs is established using binding tokens or a Circle of Trust. See Prerequisites for Federated Repositories.
• Admin permissions on both JPDs, including access to create or update repositories and configure Federation members.
• Access tokens for the source and target JPDs with permissions to read and update repository configuration.
• JFrog CLI is installed. See JFrog CLI.
• Federation Migrator plugin 2.4 or later is installed.
• Source repositories are local repositories with push replication configured to the target JPD.
• Target repositories are local or don't yet exist. The tool creates missing target repositories from the source configuration.
• No Full Sync operations are in progress on repositories you plan to migrate.

Install the Migration Plugin

Install the JFrog CLI federation-migrator plugin, which installs the required migration components and runs the repository operations.

To install the migration plugin:

1. Run the following command to install the plugin from the official registry of JFrog CLI plugins:

   Bash

   jf plugin install federation-migrator

2. Verify the installation:

   Bash

   jf federation-migrator -v

Prepare the Repository List

Identify the local repositories on the source JPD that currently use push replication to the target JPD.

Supported repository selection

Use only one input method. --repos and --repo-list-file are mutually exclusive.

Example repository list file

# Production release repositories
libs-release-local
libs-release-prod

# Snapshots
libs-snapshot-local

Repositories skipped by default

The tool skips a repository when any of the following is true:

• The source repository doesn't exist or isn't a local repository.
• The target repository exists but isn't a local repository.
• The source repository replicates to more than one target unless you pass --allow-multiple-replications.

Review your replication topology before running the migration, especially if you use multi-push replication.

Run the Migration

Run the replication_to_federation command from a machine that can reach both JPDs.

To migrate push-replicated repositories to unidirectional Federation:

1. Run the following command:

   Bash

   jf federation-migrator replication_to_federation \
     <source base url without /artifactory> \
     <source access token> \
     <target base url without /artifactory> \
     <target access token> \
     --repos <repo1,repo2,...>

   For example:

   Bash

   jf federation-migrator replication_to_federation \
     https://source.example.com \
     <source-token> \
     https://target.example.com \
     <target-token> \
     --repos libs-release-local,libs-snapshot-local

2. Alternatively, pass a repository list file:

   Bash

   jf federation-migrator replication_to_federation \
     https://source.example.com \
     <source-token> \
     https://target.example.com \
     <target-token> \
     --repo-list-file ./repos-to-migrate.txt

What the Tool Does

For each repository in your list, the migration tool performs these steps:

1. Validates that the source repository is a local repository.
2. Creates the target local repository from the source configuration if it doesn't exist.
3. Converts the source and target repositories to Federated repositories in parallel.
4. Configures Federation members so the source pushes to the target.
5. Removes legacy push replication configuration as part of the Federated conversion.
6. Triggers the initial Full Sync when Artifactory creates or updates the Federation membership.

By default, the target member is configured in receiving-only mode, which gives you unidirectional sync from source to target.

Command Options

Review the Results Report

After the command completes, the tool writes a plain-text report listing the outcome for each repository.

The command can complete even when individual repositories fail or are skipped. Use the results report, rather than command completion alone, to determine whether every repository migrated successfully.

Report location

• Default: replication-to-federation-results-<timestamp>.txt in the current working directory
• Custom path: the file you set with --output-file

Report columns

Example report

libs-release-local   SUCCESS  created on target
libs-snapshot-local  SUCCESS
legacy-multi-target  SKIPPED  source has multiple replication targets
remote-cache-local   SKIPPED  target is not a local repo

Verify Federation Health

After migration, confirm that each converted repository is healthy.

To verify Federation health:

1. In the Administration module on the source JPD, open Platform Monitoring > Federation Status and confirm the converted repositories show connected members.
2. On the target JPD, verify that migrated members appear in receiving-only mode if you used the default unidirectional configuration. See Configure Receiving-Only Mode.
3. Confirm legacy replication definitions were removed from converted repositories.
4. Wait for the automatic Full Sync to complete and confirm that the member state is healthy.
5. Deploy or resolve a test artifact on the source repository and verify it appears on the target member.
6. If synchronization doesn't complete as expected, review Troubleshooting Federated Repositories.

Frequently Asked Questions

This section provides answers to frequently asked questions.

Related Topics

• Configure Receiving-Only Mode
• Mirror Modes in Federated Repositories
• Convert Between Repository Types
• Repository Replication
• Federation Dashboard
• Migrate to the Artifactory Federation Service