Migration Tool

The Migration Tool helps you migrate repositories to new normalization rules and enforce required artifact and package naming conventions.

After you select a repository to migrate, migrations automatically complete a dry run and provide a report on which packages will migrate successfully and which are non-compliant. You can manually fix any non-compliant packages before finalizing the migration, and you can repeat the dry run to check the status of the packages.

As part of the migration setup, you can designate a repository to store any remaining non-compliant packages for later cleanup.

Requirements:

• Admin or Project Admin permissions

This topic covers the following tasks:

• Migrate a Local Repository
• Migrate a Remote Repository
• Migrate a Smart Remote Repository

Migrate a Local Repository

When you migrate a local repository, Artifactory checks all packages in the repository for compliance with the new normalization standards. If non-compliant packages are found, you can either manually fix the packages or choose to isolate them in a different repository before migration.

To migrate a local repository:

1. In the Administration module, go to Artifactory Settings > Migration Tool. The migrations table opens.

2. Click Create migration. The migration wizard opens.

3. In the New migration step, select a source repository from the list.
   The list only includes repositories of the relevant package type that are not already associated with another migration.

4. Click Save and continue to dry run. The migration is saved and starts a dry run to check the status of packages in the repository.

   📘

   Note

   The dry run may take some time to complete. You can navigate away from the migration page and access it again later from the Actions menu in the migrations table.

5. Once the dry run has completed, on the Dry run results step:

   • Review the results of the dry run and see counts of total packages in the repository, packages that comply with the new standards, and packages that failed normalization.
   • Click Download Report to view a complete list of which packages will migrate successfully and which packages are non-compliant with the new normalization. Optionally, use this information to manually fix packages.
     To repeat the dry run, return to the New migration step and click Save and continue to dry run again.

6. When you are satisfied with the state of the packages in the source repository, click Set up migration.

7. On the Migration setup step, select one of these options for handling non-compliant packages:

   • Auto-create new repository: The migration creates a new repository and moves non-compliant packages to the new repository.
   • Use existing repository: The migration moves non-compliant packages to an existing repository of your choice.

8. If you chose to use an existing repository, select a repository from the list.

9. Click Migrate. A confirmation message appears.

   🚧

   Warning

   When migration is in progress, the repository is unavailable for all developer interaction, CI pipelines, and virtual repositories. Pipelines and builds that rely on the repository will fail until the migration is complete. Migration may take up to several hours.

10. Click Migrate again to confirm.

When migration is complete, PackageBaseAddress is enabled on the normalized repository. For more information, see Package Content in the Microsoft documentation.

The normalized repository uses new normalization rules and enforces the associated layout and naming standards. All packages remaining in the normalized repository are compliant with the normalization, and non-compliant packages are moved to the designated repository.

Migrate a Remote Repository

Migrating a remote repository completes instantly. The Migration Tool makes a backup of the repository and then zaps the cache.

Prerequisites: Administrator privileges used to configure the smart remote repository.

To migrate a remote repository:

1. In the Administration module, go to Artifactory Settings > Migration Tool. The migrations table opens.

2. Click Create migration. The migration wizard opens.

3. In the New migration step, select a source repository from the list.
   The list only includes repositories of the relevant package type that are not already associated with another migration.

4. Click Save and continue to dry run. The migration is saved and starts a dry run to check the status of packages in the repository.

   📘

   Note

   The dry run may take some time to complete. You can navigate away from the migration page and access it again later from the Actions menu in the migrations table.

5. Once the dry run has completed, on the Dry run results step:

   • Review the results of the dry run and see counts of total packages in the repository, packages that comply with the new standards, and packages that failed normalization.
   • Click Download Report to view a complete list of which packages will migrate successfully and which packages are non-compliant with the new normalization. Optionally, use this information to manually fix packages. To repeat the dry run, return to the New migration step and click Save and continue to dry run again.

6. When you are satisfied with the state of the packages in the source repository, click Set up migration.

7. Click Migrate. A confirmation message appears.

8. Click Migrate again to confirm.

Migrate a Smart Remote Repository

Smart remote repositories proxy repositories in another instance of Artifactory. The origin repository must be migrated before the smart remote repository is migrated. Once the origin repository is migrated, smart remote migration can be completed instantly.

To migrate a smart remote repository:

1. In the Administration module, go to Artifactory Settings > Migration Tool. The migrations table opens.
2. Click Create migration. The migration wizard opens.
3. In the New migration step, select a source repository from the list.
   The list only includes repositories of the relevant package type that are not already associated with another migration.
4. Click Save and continue to dry run. The migration is saved and starts a dry run to check the status of packages in the repository.
5. Once the dry run has completed, on the Dry run results step:

   • If the origin proxied by the smart remote repository hasn't been migrated, click Save for later to save the smart remote repository migration.

     Migrate the origin repository first, then return to the saved smart remote migration from the Actions menu on the migrations table.

   • If the origin proxied by the smart remote repository has been migrated, click Set up migration.

6. On the Migration setup step, click Migrate. A confirmation message appears.
7. Click Migrate again to confirm.

Manage Migrations

You can manage migrations from the migrations table on the Migration Tool page:

• You can filter the table by status using All Migrations, In Progress, or Migrated. The In Progress filter includes dry runs that are running, dry runs that have finished, and migrations that are still running.
• Depending on each migration's status, the Actions menu can include:
  • Migrate: Opens the migration setup to initiate migration.
  • Dry Run: Immediately starts another dry run.
  • View: Opens the migration and displays the saved configuration.
  • Download Last Report: Downloads the latest dry run report.
• You can use additional filters and column customization to control which migrations appear in the table.

Best Practices for NuGet Normalization

JFrog recommends the following best practices when normalizing NuGet repositories with the Migration Tool.

This section also covers:

• Understanding Normalized Versions
• Resolving Duplicate Versions After Migration

Normalization converts NuGet package versions to a single standard form. Artifactory's NuGet V3 PackageBaseAddress API is the flat container endpoint that modern NuGet clients use to restore packages. You can only use this API on repositories with Enforce Layout enabled. Clients that only speak the older NuGet V2 protocol, such as Chocolatey and PowerShellGet, don't need Enforce Layout and can continue using non-normalized repositories.

For more information, see NuGet Enforce Layout.

You can only set Enforce Layout when you create a repository. You can't toggle it on an existing repository. Use the Migration Tool to bring an existing local or remote NuGet repository to a normalized state.

When you plan and run a migration, JFrog recommends:

• Run a dry run first: Review the compliant and non-compliant package report before migrating any packages.
• Migrate virtual members first: Migrating virtual repositories isn't supported yet. Migrate each member repository individually before you include it in a virtual repository.
• Decide the isolation target: Before you start, choose whether non-compliant packages go to an auto-created isolation repository or an existing repository.
• Plan for paired repositories: Federated, replicated, and smart remote repository pairs must use the same normalization setting on both repositories. Both repositories in the pair must be normalized, or both must be non-normalized. Plan coordinated migrations for paired repositories, or remove or reconfigure the pairing until both repositories match.
• Apply a duplicate-resolution policy: Decide how to handle collisions before you re-upload isolated packages. For more information, see Resolving Duplicate Versions After Migration.
• Re-upload isolated packages: After migration, re-upload isolated packages under their corrected, normalized names. Non-compliant packages move to the isolation repository unchanged. They aren't renamed.
• Enable Enforce Layout on new repositories: When you create new NuGet repositories, enable Enforce Layout at creation time so new packages stay normalized going forward.
• Confirm normalization after restore: If you archive and later restore a NuGet repository, check that the restored repository has the same normalization setting as the original. If you restore into a repository with a different setting, Artifactory may reject the packages.

Understanding Normalized Versions

A version is normalized when it's written as Major.Minor.Patch, with at least three segments, no leading zeros, no trailing .0 fourth segment, and no build metadata suffix. NuGet treats 1, 1.0, 1.0.0, and 1.0.0.0 as the same version. Normalization picks one form so a single release doesn't end up stored under multiple filenames.

The following examples show how Artifactory normalizes versions.

Normalization rewrites valid Semantic Versioning (SemVer) versions into standard form. Artifactory rejects a package whose version doesn't follow SemVer at all. You can't upload that package to a normalized repository.

Resolving Duplicate Versions After Migration

Two non-normalized versions can normalize to the same string. For example, 1.0.0+123 and 1.0.0+234 both become 1.0.0, because build metadata is stripped entirely regardless of its value. The Migration Tool doesn't detect this during migration. Both packages move to the isolation repository under their original names. The duplicate appears only when you re-upload, and Artifactory rejects the second package as a conflict.

Set a resolution policy before migrating, rather than deciding case by case:

• Prefer first-party packages: Prefer a first-party package over a third-party or open-source package with the same coordinates.
• Prefer the primary team owner: If both are first-party, prefer the package owned by the repository's primary team over one in a shared or aggregate repository.
• Prefer verified publishers: Prefer a package from a known, verified publisher over one from an unverified source.
• Prefer the most recent package: If the previous rules don't pick a winner, keep the most recently published package.
• Keep both when unresolved: If you still can't decide, leave both packages in the isolation repository under their original names and resolve the conflict later.

Limitations and Usage Notes

The following are limitations and usage notes for the Migration Tool in Artifactory:

• Virtual repositories: Migrating virtual repositories isn't supported yet.
• Non-compliant packages: As part of the migration, all packages that don't comply with the new normalization standards are isolated in the selected repository. If all packages in the repository are non-compliant, the repository is emptied and all functions that rely on the content of the migrated repository will break.
• Paired repositories: Federation, replication, and smart remote repositories require both repositories to use the same NuGet repository type: normalized with normalized, or non-normalized with non-normalized. For more information, see Limitations on NuGet Enforce Layout.

Frequently Asked Questions

This section provides answers to frequently asked questions.

Related Topics

• NuGet Enforce Layout
• Limitations on NuGet Enforce Layout
• Local Repositories
• Remote Repositories
• Virtual Repositories