Migrating from TFS (or ADO Server) to Azure DevOps

So you have Team Foundation Server or Azure DevOps Server (the new name for TFS as of 2019-ish) and you’ve decided to get that thing up to Azure (specifically, Azure DevOps Services). Great! Now what? This post will walk you through the most common options and approaches and provide some gotchas along the way.

(For the sake of being concise, I’m going to refer to the on-premises instance as “TFS”. But know that this is interchangeable with ADO Server. Azure DevOps Services (the cloud-hosted version) will be referred to as “ADO”.)

TFS & ADO – What’s the Difference?

First, it’s important to understand the main differences between TFS and ADO. This Learn article goes into plenty more detail, but the key differences are:

Feature	TFS	ADO
Server Management	You manage	Microsoft manages
Expenditures	Capital (servers, licenses)	Operational (subscriptions)
Authentication	Windows Authentication/Active Directory	Microsoft Account or Azure Active Directory (highly recommended)
Reporting	SQL Server Analysis Services	Analytics Service

Basic differences between TFS and ADO

There are differences in nomenclature as well. For example, in TFS the root container of projects (of a single deployment) is a Project Collection. In ADO, it’s an organization.

Migration – An Honest Discussion

When migrating to ADO, most people automatically look to move everything they have in TFS into ADO. We always recommend having a heart-to-heart with your teams to see if that’s actually necessary. I bet you have some old projects in there that aren’t used anymore, or branches of code that need to die on the vine. Do you absolutely need to bring over all that dead weight into your new environment? What you decide to do will impact your migration approach.

Weighing your Migration Options

There are several approaches to migrating from TFS to ADO. Let’s walk through the main ones (FYI, the first 3 options discussed here are also covered in MS Learn documentation):

Start Fresh

Maybe you don’t need to bring everything you’ve ever put into TFS to ADO. If you are fine with cutting over with your most important assets from TFS and are willing to abandon a decent amount of history (and baggage), manually importing stuff is your best route.

Typically, the most common assets to keep are source code (and even then, not all history, but either current revisions or key labeled code). Pipelines (esp. if not YAML-based), test plans, etc. are more difficult to migrate.

This is by far the easiest approach, but the lowest fidelity.

Moving source code
- You can always just take the tip revisions of your master branch and throw it into a new repo (TFVC or Git) in ADO, easy peasy. But yes, you do lose all history.
- Moving from Git? Awesome – Git is portable by design. You can simply follow this documentation to import your existing repo (the only hitch is that the TFS repo must be accessible from ADO).
- Moving from TFVC? The only catch here is that the tooling to do this will migrate your TFVC repo to Git. The docs are here. If this will be your team’s first time using Git, I’d recommend reviewing these docs as well:
  - Migrate to Git from centralized version control – Azure DevOps | Microsoft Learn
  - Migrate from TFVC to Git – Azure DevOps | Microsoft Learn
Moving work items
- Excel may be your best friend here. Use the integration with Excel to export the work items you wish to move from TFS, and import them into your target project in ADO. You can also import/export via CSV format as well.
  - Import or update work items in bulk by using CSV files – Azure Boards | Microsoft Learn

Use the Migration Tool

Let’s say you decide your team needs to bring over as much as possible, including history of source code, work items, etc.

Microsoft provides a high-fidelity migration tool to help here. All the nitty-gritty details about the migration tooling and surrounding process are documented in this migration guide.

The migration guide goes over all the details, but here are the key limitations and conditions you need to be aware of:

Your version of TFS needs to be within 2 releases (minor releases) of the current version. This means you definitely need to be on Azure DevOps Server. As of this writing, you need to be on Azure DevOps Server 2020.1.1 or later. If you’re behind, you’ll need to upgrade your on-premises installation first. This documentation is updated to reflect what version you need to have in order to get support in using the migration tool.
If you’re not already using it, you’ll need to get your identities migrated or synchronized with Azure Active Directory.
The migration tool will only migrate/import data into a new, empty ADO organization. You can’t use this tool to consolidate orgs or deployments.
If your existing backend SQL database is too big, the migration tool will direct you to use an alternate method to bring in your database (TLDR it involves setting up a SQL Azure VM & importing that way).
There are a few items that the migration tool will NOT import:
- Extensions
- Services hooks
- Load test data
- Mentions
- Project Server Integrations (doesn’t exist for ADO)

Again, the migration guide (https://aka.ms/AzureDevOpsImport) is your friend.

Go the API Route

This approach sits in between “Start Fresh” and “Migrate” in terms of fidelity. You can utilize the Azure DevOps APIs to roll your own migration utility, or leverage some 3rd party options (such as OpsHub or TaskTop).

This option also carries its pros and cons. It’s more work for you, but you get more control. A 3rd party route will carry a cost.

Get Help

Microsoft has a terrific partner ecosystem that can be called upon to help you with migration as well. They have a ton of experience with the approaches I called out above, and some may have their own tooling or methods as well. If you’d like help connecting to one of those partners, reach out to your Microsoft contact (or ping me if you’re not sure who that is).

Wrapping Up

I hope you find this helpful when considering your move from TFS (or ADO Server) to Azure DevOps Services. If you have other tools you are thinking about migrating from, there may be options for those as well: but that’s for another blog post in the future.

Have a look at the below links for additional information on this topic.

Steve Says

Emails that should've been posts