Migration Tool

The Migration Tool migrates existing NuGet local, remote, smart remote, and virtual repositories to a normalized layout. You can set Enforce Layout only when you create a repository. Use the Migration Tool for repositories that were created without Enforce Layout. For more information, see NuGet Enforce Layout.

After you select a repository to migrate, the Migration Tool completes a dry run. For local and remote repositories, the report identifies compliant and non-compliant packages. For smart remote repositories, the report shows whether the origin repository is already migrated. For virtual repositories, the report identifies normalized and non-normalized included repositories.

When you migrate a local repository, you can designate a repository to store remaining non-compliant packages for later cleanup. Remote and smart remote migrations don't isolate packages. Virtual repositories don't store packages and don't require an isolation repository.

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 Virtual 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 Artifactory finds non-compliant packages, 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 Select repository step, select a source repository from the list.
   The list only includes repositories of the relevant package type that aren't 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 Total Packages, Normalized, and Failed Normalization.

   Normalized is the number of packages that already follow the normalization rules and will migrate successfully. Failed Normalization is the number of packages that don't follow those rules. During migration, you can move the packages that failed normalization to an isolation repository. For more information, see Understanding Normalized Versions.

6. Click Download Report to view a complete list of which packages will migrate successfully and which packages are non-compliant with the new normalization.

   • (Optional) Use this information to manually fix packages.
   • (Optional) To repeat the dry run, return to the Select repository step and click Save and continue to dry run again.

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

8. On the Finalize migration 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.

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

10. Click Migrate. A confirmation message appears.

11. 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 Artifactory moves non-compliant packages 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.

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 Select repository step, select a source repository from the list.
   The list only includes repositories of the relevant package type that aren't 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 Total Packages, Normalized, and Failed Normalization.

   Normalized is the number of packages that already follow the normalization rules and will migrate successfully. Failed Normalization is the number of packages that don't follow those rules. A remote migration doesn't move those packages to an isolation repository. For more information, see Understanding Normalized Versions.

6. Click Download Report to view a complete list of which packages will migrate successfully and which packages are non-compliant with the new normalization.

   • (Optional) Use this information to manually fix packages.
   • (Optional) To repeat the dry run, return to the Select repository step and click Save and continue to dry run again.

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

8. Click Migrate. A confirmation message appears.

9. Click Migrate again to confirm.

Migrate a Smart Remote Repository

Smart remote repositories proxy repositories in another Artifactory endpoint. You must migrate the origin repository before you migrate the smart remote repository. After you migrate the origin repository, you can complete the smart remote migration instantly.

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

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 Select repository step, select a source repository from the list.
   The list only includes repositories of the relevant package type that aren't 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.
     1. Migrate the origin repository first.
     2. 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 Finalize migration step, click Migrate. A confirmation message appears.
7. Click Migrate again to confirm.

Migrate a Virtual Repository

A virtual NuGet repository aggregates local, remote, and virtual repositories and doesn't store packages of its own. A virtual migration doesn't isolate or move packages. The Migration Tool checks each included repository, then marks the virtual repository as normalized when every included repository is already normalized.

You can keep a migrated, normalized repository in a non-normalized virtual repository while you finish the remaining included repositories. A normalized virtual repository can include only normalized repositories.

To migrate a virtual 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 Select repository step, select a source virtual repository from the list.
   The list only includes repositories of the relevant package type that aren't already associated with another migration.

4. Click Save and continue to dry run. The migration is saved and starts a dry run that scans every included repository.

   📘

   Note

   The dry run reports repository counts, not package counts. 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 Total Repositories, Normalized, and Failed Normalization.

   The dry run counts included repositories. Normalized is the number of included repositories that are already normalized. Failed Normalization is the number of included repositories that aren't normalized. Migrate each repository counted under Failed Normalization before you migrate the virtual repository.

6. Click Download Report to view the included repositories and their normalization status.

7. On the Dry run results step:

   • If any included repository isn't normalized:
     1. Use one of the following actions for that repository:
        • Create Migration: Create a migration when one hasn't been started.
        • View Migration: Open an existing migration.
        • Download Last Report: Download the repository's latest completed dry-run or migration report.
     2. Click Save for later.
     3. Migrate each remaining included repository. Use the procedure that matches the repository type.
     4. Return to the saved virtual migration.
   • If every included repository is normalized, click Set up migration.

8. On the Finalize migration step, verify that the Ready to migrate message appears.

9. Click Migrate.

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

Use the following best practices when you normalize 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. You can use the Migration Tool to bring an existing local, remote, or virtual NuGet repository to a normalized state.

When you plan and run a migration:

• Run a dry run first: Review the compliant and non-compliant package report before migrating any packages.
• Migrate included repositories first: Migrate each included repository, then migrate the virtual repository. If any included repository isn't normalized, the virtual migration doesn't change the virtual repository and its report identifies the repositories that you must migrate first.
• 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. Artifactory moves non-compliant packages to the isolation repository unchanged and doesn't rename them.
• 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 Artifactory doesn't store a single release 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 Artifactory strips build metadata entirely regardless of its value.

The Migration Tool doesn't detect this during migration. Artifactory moves both packages 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.

You can 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: A virtual repository migrates only after you normalize every included repository. The Migration Tool doesn't move packages out of a virtual repository. A non-normalized virtual repository can include normalized repositories. A normalized virtual repository can include only normalized repositories.
• Non-compliant packages: The migration isolates packages that don't comply with the normalization rules in the repository you select. If every package in the repository is non-compliant, the migration empties the repository, and builds or clients that depend on its content fail.
• 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