How do you migrate from TFS or Azure DevOps Server to Azure DevOps Services using the Data Migration Tool?

Think of migrating from Azure DevOps Server to Services like moving an entire museum collection from one building to another across the country. You cannot simply load paintings into a truck: each piece must be cataloged, wrapped in appropriate protective materials, transported in climate-controlled vehicles, and reinstalled in the new building with the same spatial relationships, labels, and security settings. The catalog (identities) must be translated because room numbers (Active Directory SIDs) are different in the new building (Azure AD). The Data Migration Tool is the professional moving company that handles all of this complexity: it exports the database, ships it to Azure, imports it, and maps the old identity references to new ones.

The migration begins with preparation and validation. You must be running a supported version of Azure DevOps Server (2019 or later, with latest updates). The Data Migration Tool validates your collection against a set of readiness checks: unsupported field types, oversized attachments, deprecated features in use, identity conflicts, and data integrity issues. Common blocking issues include Git repositories exceeding 10GB, TFVC files exceeding 1GB, custom process templates with unsupported elements, and work items with more than 1000 revisions. The validation report identifies these issues and provides remediation guidance. Some issues require modifying data before migration; others simply generate warnings about features that will behave differently in Services.

The actual migration process has two modes: dry run (import with no data, just validation) and production import. For the production import, you generate a DACPAC (Data-Tier Application Package) from your collection database using SQL Server tools. This DACPAC is a compressed export of the entire database schema and data. You upload the DACPAC to an Azure blob storage container provided by Microsoft during the import setup. For large databases, this upload can take hours or days depending on bandwidth. Microsoft then processes the import on their infrastructure, applying schema transformations to adapt the on-premises database structure to the multi-tenant Services format. The import duration depends on database size: small collections (under 10GB) complete in hours, while large collections (500GB+) may take days.

Identity mapping is the most complex aspect of the migration. On-premises Azure DevOps Server uses Active Directory (AD) security identifiers (SIDs) for all permissions, work item assignments, and history attribution. Azure DevOps Services uses Azure Active Directory (Azure AD) identities. The migration tool generates an identity map file listing every AD identity referenced in the collection and requiring you to map each to a corresponding Azure AD identity. For organizations that have already synchronized their AD to Azure AD using Azure AD Connect, many mappings are automatic. For identities that have no Azure AD equivalent (departed employees, service accounts, renamed accounts), you must decide whether to map them to existing Azure AD accounts or leave them as historical references. Incorrect identity mapping results in permission errors and misattributed history.

Post-migration validation and cutover planning are critical. During migration, the source Server is taken offline (or set to read-only) to prevent changes that would not be captured in the migration. After import completes, you validate that all repositories, work items, pipelines, and permissions exist correctly in Services. Pipelines need reconfiguration because Service Connections, agent pools, and variable groups do not migrate automatically. Self-hosted agents must be re-registered to point to the new Services organization. External integrations (webhooks, API clients, IDE connections) must be updated to use the new dev.azure.com URLs. Plan a cutover window that accounts for DNS changes, client reconfiguration, and team communication.

The production gotcha is underestimating the identity mapping effort and the pipeline reconfiguration work. Organizations with 10+ years of TFS history have thousands of unique identities from employees who have left, contractors, and service accounts. Each must be manually reviewed and mapped. Another common issue is TFVC workspace configuration: developers with local TFVC workspaces must recreate them pointing to the new Services instance. Pipeline migration requires recreating every Service Connection, variable group, and agent pool in the new organization, then updating pipeline YAML to reference the new resource names. Budget 2-4 weeks of effort beyond the actual data migration for this reconfiguration work.