Work items migration between Azure DevOps projects
Some things were much simpler when they were not in the cloud. Let’s take for example the good old Microsoft Team Foundation Server. In the past when we wanted to move data (code, work items, etc.) between system instances the only required thing was the knowledge about doing database backup’s, restoring it, and running some tools provided with the TFS server itself. And now a few years later we are in the cloud, TFS was rebranded to Azure DevOps and what’s most important from the data migrations’ perspective – we don’t have access to the databases of our service’s instance anymore.
Ok. Right now, the code repository is based on GIT (is anyone still using the old VSSC? Seriously?) which should make moving it between repositories’ instances quite a simple thing. And that is true. Migration of source code and the whole repository content, including its history, is a simple and nice process with GIT command-line tools. What about other Azure DevOps content? When we’re talking about Build Pipelines, the best practice would be to store them in the repository as YAML files. Of course, it is not possible in the case of Release’s ones (damn you Microsoft! 😉). Other elements like dashboards, wikis, and artifacts should also be movable with very little effort. But what about work items (tasks, user stories, buts, etc.)? Very often, we have hundreds or thousands of those in our DevOps instances. Of course, work item migration is possible with the API. We just need to write some code or use some dedicated ELT platform (for example, the good old Microsoft SQL Server Integration Services). In both cases, the amount of work involved in implementing migration tools may be considerable. Fortunately, someone has already done it for us. Ladies and gentlemen, let me introduce the Azure DevOps Migration Tools!
Azure DevOps Migration Tools give us the possibility of migrating work items (including revisions and git commit links) and their attachments between Azure DevOps projects. The important thing is that projects don’t need to be in the same Azure Active Directory tenant. We may download it for free or install it with the Chocolatey packages manager (Chocolatey Software | Azure DevOps Migration Tools 13.0.3.0). After installation, the tool is ready to work. The only thing we need to do is edit the JSON configuration file (a sample of this file may be found here: v1 Reference Overview | Azure DevOps Migration Tools (nkdagility.com)). Because the application’s documentation is clear and all the options available in the configuration file are kind of self-describing, I won’t waste your time going through its them here. You can always go to its GitHub site (https://github.com/nkdAgility/azure-devops-migration-tools/) and do a quick look. And of course, investigate the source code, which is a great source of knowledge about interacting with the Azure DevOps API and its artifacts.
Few tips and things worth mentioning:
The great thing that is possible with Migration Tools is migrating images and updating their links inside work item text content (description and comments). This is something that is not easily achievable with default DevOps API calls.
However, to make it work, you need to authenticate with a DevOps personal access token. The mentioned feature won’t work if you enter your credentials inside the Power Shell prompt window.
The possibility of verbose logging is a great feature, but it makes the migration process much longer. Avoid it until it is necessary.
Remember to add the Reflecting Work Item ID field in your DevOps destination environment. Because it is not possible to migrate work item identifiers from the source environment, having references (links) to the reflecting work item in the source environment is extremely useful in case of migration error investigation.
In the case of having lots of attachments (files, images, etc.) in your source environment, provide sufficient space on the local hard drive where Migration Tools are set up. All the files are placed in the temporary folder on the mentioned HDD.
By default, there is a so-called "migration comment" added to every migrated work item, but you may disable this feature inside the configuration file.
It is good practice to disable notifications in the destination DevOps environment. If not, there is a risk that team members will be spammed with hundreds of emails about events that took place in the past inside the migration source environment.
It is possible to limit the number of migrated work items with the Work Item Query Language. It is a great feature for experiments when you don’t want to migrate thousands of WI just to check how the tool behaves in the case of one of the available flags being set to "true".
In the case of having my destination project inside a free DevOps organization, during migration I started to see DevOps warnings about generating too much traffic and limiting access to related APIs. It does not affect the migration process in any way. Ok. I assume it may make it slower. I did not observe this issue in the commercial, paid Azure DevOps instances.