Migration Tool

📘
Note
As of Artifactory SaaS 7.152.1, you can use the Migration Tool to normalize NuGet repositories. Other migration types may be available in future releases.

The Migration Tool helps administrators 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 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.

🚧
Important
When a 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.
After the migration is complete, non-compliant packages are moved from the migrated repository to the repository you selected.

Requirements:

Admin or Project Admin permissions

Migrate a Local Repository

When you migrate a local repository, all packages inside the repository are checked 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:

On the Administration module, navigate to Artifactory Settings > Migration Tool. The migrations table opens.
Click Create migration. The migration wizard opens.
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.
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 Actions menu in the migrations table.
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 package 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.
When you are satisfied with the state of the packages in the source repository, click Set up migration.
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.
If you chose to use an existing repository, select a repository from the list.
Click Migrate. A confirmation message appears.

🚧
Important
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.
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 is instantaneous. The Migration Tool makes a backup of the repository and then zaps the cache.

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

To migrate a remote repository:

On the Administration module, navigate to Artifactory Settings > Migration Tool. The migrations table opens.
Click Create migration. The migration wizard opens.
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.
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 Actions menu in the migrations table.
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 package 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.
When you are satisfied with the state of the packages in the source repository, click Set up migration.
Click Migrate. A confirmation message appears.
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 instantaneously.

To migrate a smart remote repository:

On the Administration module, navigate to Artifactory Settings > Migration Tool. The migrations table opens.
Click Create migration. The migration wizard opens.
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.
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.
Once the dry run has completed, on the Dry run results step:
- If the origin proxied by the smart remote repository has not 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.
On the Migration setup step, click Migrate. A confirmation appears.
Click Migrate again to confirm.

Manage Migrations

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

Click All Migrations, In Progress, or Migrated to view migrations by status. In Progress includes dry runs in progress, dry runs completed, and migrations in progress.
Use the options in the Actions menu. Depending on the migration status, some actions may not be available:
- Migrate: Open the migration setup to initiate migration.
- Dry Run: Immediately start another dry run.
- View: Open the new migration and view saved configuration.
- Download Last Report: Download the latest dry run report.
Use filters and column customization to control which migrations appear in the table.

Limitations and Usage Notes

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

Virtual repositories: Migrating virtual repositories is not yet supported.
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 ends 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.

🚧
Warning
If you migrate a paired repository so that it becomes normalized while the other end stays non-normalized, the repositories will no longer function as intended. Plan coordinated migrations for paired repositories, or remove or reconfigure federation and replication until both repositories match.