Before you use the Azure DevOps Data Migration Tool to migrate your database with high fidelity, it’s important to understand the key concepts and considerations involved in the migration process.

Understand What Data Gets Migrated

Not all data gets migrated during the process. Separate databases outside the collection, such as reporting and SharePoint data, do not get migrated. Here’s a breakdown of what is and isn’t included:

Included Data

  • Collection Mapping: Each collection in Azure DevOps Server corresponds to one database. During migration, the entire collection - including work items, history, Team Foundation Version Control (TFVC) changesets, Git data, build definitions, and more - gets migrated to Azure DevOps Services. Work item, TFVC changeset, and Git commit numbers/IDs remain unchanged.

Excluded Data

  • Extensions: Extensions must be reinstalled post-migration. You should publish local extensions to the Marketplace as private extensions and share them with the account.
  • Service Hooks: Service Hooks data isn’t included in the migration; you’ll need to reconfigure them after migration.
  • Load Tests: Load test data isn’t brought over; you’ll need to reconfigure load tests after migration.
  • Pipeline Agents and Agent Pools: You’ll need to reconfigure pipeline agents and agent pools after migration.
  • Mentions: User mentions in work item discussions retain on-premises identity, not the new Microsoft Entra ID. Hovering on usernames won’t display contact cards, and some hyperlinks might be invalid.
  • Project Server Integrations: These are not available for Azure DevOps Services, such as XAML Builds, Microsoft Test Manager, SharePoint, SQL Data Warehouse, etc.
  • Preview Features: Some Azure DevOps Server features can be previewed during migration to Azure DevOps Services.

Understand Project Limits

If your collection contains numerous projects, Azure DevOps Services imposes a limit of 1,000 projects per organization, although it’s recommended to keep it under 300. Beyond this threshold, certain experiences like connecting to the organization from Visual Studio might degrade. To stay within the limit, consider splitting the collection or deleting older projects.

Mapping On-Premises Databases to Azure DevOps Organizations

It’s important to understand how the database migration process works at a high level. Migrations operate on the following main concepts:

  • Team Project Collection: Collections in Azure DevOps Server are physical containers for team projects and their artifacts. Each collection equates to a single SQL database and is the source for migrations to Azure DevOps Services.
  • Azure DevOps Services Organization: Organizations are the management unit in the cloud-hosted service. They map 1:1 to the concept of a team project collection in Azure DevOps Server, and are the destination for migrations.

When you migrate a team project collection SQL database, the Data Migration Tool creates a new Azure DevOps organization with a user-provided name. Migrating a collection database into an existing Azure DevOps Services organization or consolidating multiple collection databases into a single organization is not possible - the mapping is strictly one-to-one.

Choose Your Data Center Location

When setting up your Azure DevOps Services organization, you can choose the location for your data. During initial sign-up and organization creation, select a region that suits your needs. Make a note of the region’s shorthand code to use later for migration.

Understand Pricing and Licensing

A common question is what type of licensing is needed to use Azure DevOps Services. The good news is you likely already have the licenses you need. We’ve provided a worksheet to help you determine the right licensing:

# Column 1 Column 2
1 Number of team members
2 Number of stakeholders
3 Subtract line 2 from line 1*
4 # of Visual Studio subscribers**
5 Subtract line 4 from line 3
6 Subtract line 5 from line 5***

*Stakeholders are free **Visual Studio Subscribers have Azure DevOps Services included ***Each Azure DevOps Services organization gets five free users

For more details on cost-effective options, check out the Billing overview and the Azure Pricing Calculator.

In addition to the core features, Azure DevOps offers value-added services like hosted load testing, Test Manager extensions, and a wide range of integrations and extensions. Evaluate your requirements and budget accordingly, as some of these may come with extra costs.

Reserve Your New Organization Name

To ensure your desired organization name is available for the final migration, we recommend reserving it early on. Follow these steps:

  1. Initial Reservation:
    1. Create an organization with a temporary name, e.g., https://dev.azure.com/contoso-temporary.
    2. Reserve this temporary name for your future migration.
  2. Final Migration:
    1. Perform the final migration into the https://dev.azure.com/contoso-temporary organization.
    2. After successful migration, rename the reserved organization to open your desired name, e.g., https://dev.azure.com/contoso.
    3. Immediately rename the migrated organization to the desired name.
    4. (Optional) You can now delete the originally reserved and renamed organization.

By following this approach, you can ensure a smooth transition while keeping your preferred organization name available.

Now that you have a solid understanding of the key concepts, you’re ready to complete the prerequisites for migration.