Azure DevOps Migration Tools moves work items across organizations, and admits it is for experts

Crossing project, collection and organization boundaries

The Azure DevOps Migration Tools allow you to bulk edit and migrate data between Team Projects on both Microsoft Team Foundation Server and Azure DevOps Services. The repository description spells out the scope: Teams, Backlogs, Work Items, Tasks, Test Cases, and Plans and Suites can be moved from one project to another, both within the same organisation and between organisations.

The key term in the README is location, and the tool defines it explicitly: locations include Projects, Collections and Organizations. That definition is what makes the tool more than a copy script. A copy script moves work items from one project to another inside one organisation. These tools move work items from a collection on a TFS server to a project in an Azure DevOps Services organisation, and they can do it in the other direction too.

The README states the compatibility position plainly: the tools support connecting to Team Foundation Server 2013 and newer, Azure DevOps Server, and Azure DevOps Services, they support both hosted and on-premise instances, and they can move data between any two of them. Any source to any target, with version 2013 as the floor.

The audience follows from that. This is for organisations consolidating or restructuring Azure DevOps estates, and for the one-off projects where a team has decided to move a work item history from an old on-premise server into the cloud service and cannot find a supported path for it.

Move, merge, split, change process, bulk edit

The capability list in the README is short enough to be worth reading line by line, because it maps onto the operations an organisation actually needs.

Move work items, test plans and suites, and pipelines between projects, collections and organizations. Merge multiple projects into a single project, even from different organizations. Split one project into several projects, again across projects, collections and organizations. Change the process from Agile to Scrum or any other template. And bulk edit work items.

The merge and split operations are the ones that have no obvious equivalent elsewhere, because they are not moves at all. Merging two projects into one is a many-to-one operation that has to decide what happens to the shared work item ids, the iterations, the area paths and the shared queries. Splitting is the reverse. The README says the tool was developed by 100 plus contributors from the Azure DevOps community to handle various scenarios and edge cases, and then says directly: not all cases are supported.

That last sentence is the most important line in the README for an adopter, and it is paired with another: the tool is intended for experienced users familiar with TFS and Azure DevOps object models and debugging in Visual Studio.

What each object type carries with it

The per-type details are where the real cost of a migration shows up, so they are worth taking one at a time.

Work items are supported including links and attachments, with custom mappings for fields and types. You can copy work items between locations with history, which means the revision trail comes across rather than arriving as a single new creation. The tool also lets you bulk edit work items in place, which the README points at as useful for cleaning up data and for process template changes. Teams and shared queries can be included optionally.

Test plans and suites copy with their configurations, shared steps and shared parameters, so a test plan does not arrive stripped of the shared fixtures its cases depend on.

Pipelines copy too, with one stated exclusion: XAML and Classic Builds and Release are excluded. That is a real boundary, because a repository that still holds classic release definitions is only partly migrated.

Processes copy as well, which is what makes the process template change possible, and it is the piece that has to be right before any of the work item moves can succeed, since the target's process defines the fields and states that work items will land in.

Where to get it, and the Windows only constraint

The README does not give a command line install, and that is deliberate, because the tools run on Windows. It points instead at the documentation site, devopsmigration.io, which has a dedicated Installation page along with Permissions, Getting Started and a Configuration Reference.

The distribution options the README does name are the GitHub repository and a Winget package named nkdAgility.AzureDevOpsMigrationTools. Questions are asked on GitHub Discussions, and the project credits Martin Hinshelwood as creator and maintainer.

The Windows constraint is the first thing to check, because it eliminates a large class of user. The CI setup in the repository badges points at Azure DevOps rather than GitHub Actions, and the build is Visual Studio based, with a .vs/ directory and a .vscode/ directory in the tree. A migration team on macOS or Linux will need a Windows host, and for a tool that talks to TFS servers that are often reachable only from a corporate network, that host is often a specific machine anyway.

The repository also carries a Configuration Reference in its own docs/ directory, along with the change log, a spellcheck wordlist and a Gemfile, which is a sign of a documentation setup that is maintained with the code rather than separately.

Configuration lives in JSON files, and there are many of them

The repository layout gives a clear picture of how the tool is configured, and the top level is full of sample configurations.

There are files named configuration-default.json, configuration3-default.json, configuration-classic.json, configuration-classic2.json, configuration-classic2-wit.json and configuration-classic2-pipeline.json, plus configuration-classic2 entries that vary by whether the migration is about work items or pipelines. There is a test-config.json and a Local.testsettings file, and a MigrationTools.lutconfig at the root, which is presumably a lookup table configuration given the name.

The pattern of classic2 variants, split by work item and pipeline, suggests the configuration is a per-migration-kind document rather than one global settings file, and the appsettings.json at the root is the application level configuration alongside it. The .backup/ directory at the top level is a further hint about what happens before data moves.

For a user, the practical consequence is that the configuration is a large, hand-edited JSON document that describes the source, the target and the mapping between them, and getting it right is most of the work. The Configuration Reference in the documentation is the thing to read before the first run, not after it.

This is also the point where the tool differs from a script. The mapping of fields and types between two organisations with different process templates is expressed as configuration, which means it can be reviewed, versioned and reused, and also that it is a large amount of JSON to get right.

Preview releases, telemetry, and a project that admits its limits

Two aspects of the project's presentation deserve a straight reading.

First, the release cadence. The three most recent releases are v16.3.4-Preview.37 on 2026-10-15, v16.3.4-Preview.36 on 2026-10-14 and v16.3.4-Preview.35 on 2026-10-14, and the GitHub pre-release badge is separate from the release badge, which means the tagged builds are previews rather than stable releases. The README also points the preview documentation at a separate preview site. The repository is not archived and the last push was on 2026-10-15, so the work is current, but the version you install is explicitly a preview.

Second, the metrics section, which reports usage figures that come from Application Insights and are described as experimental and possibly not accurate, updated every ten minutes. The table counts work items processed and the average time a work item takes to process, with a note that the counts are of work items processed. Reading this as a quality signal would be a mistake, since the README itself says the numbers are experimental.

The honest framing of the project is in the README rather than in the badges: more than a hundred contributors from the Azure DevOps community, built to handle various scenarios and edge cases, intended for experienced users, with not all cases supported. The badges for build status, tests, coverage, maintainability, security and vulnerabilities come from Azure DevOps and SonarCloud, which is at least a visible quality pipeline for a tool that touches production work item data.

What this tool cannot do, and when to reach for something else

There are clear boundaries, and they are the reasons to think twice before adopting.

Classic build and release definitions do not migrate. XAML does not migrate. If your estate is still running classic release pipelines, you will be doing that part by hand, and the tool will not tell you so, because the exclusion is simply silent.

Process and field mappings are not fully automatic. The README mentions custom mappings for fields and types, which means the mapping is something you define, and for a project whose process has been customised over years, producing that mapping is the bulk of the effort.

The tool runs on Windows only, and the README is explicit that it is intended for users who can debug in Visual Studio. A team that wants a cross-platform migration utility, or one that wants a tool with a friendly interface for occasional bulk edits, is looking at the wrong shape of product.

And the failure mode is worth naming. This tool writes to production work item stores. A partially applied migration, or a mapping that drops links and attachments, is not something you can undo with a flag. The tool's own backup facility and the Permissions page in the documentation are not optional reading for a first run.

AGPLv3, a commercial option, and who this is for

The licence is AGPL-3.0, with the text in the LICENSE file at the top of the repository. For a tool most organisations run as an internal utility against their own Azure DevOps instance, that is rarely the deciding factor, but it is worth knowing before you redistribute a modified build or embed parts of it in another product.

The support model is stated in the README. Community support is available through GitHub Discussions, and for paid support the README points to Azure DevOps Migration Services from nkdAgility, the company behind the project. There is also a YouTube channel and an Elmah.io sponsorship badge, so the project funds its own infrastructure in part through sponsorship.

So who should adopt it? A team with an Azure DevOps consolidation or migration on the horizon, a Windows machine available, and someone who is already fluent in the Azure DevOps object model. That person is the requirement, and the README names it. Without that person, the tool is a large JSON document with a mapping problem in front of it, and the reference documentation on devopsmigration.io is the resource that decides whether the attempt is worth making.

What should not adopt it is anyone who wants a bulk edit UI for a single project, since the same need is served by lighter tools, or anyone who needs classic release pipelines to move.

Editorial conclusion

Adopt Azure DevOps Migration Tools if you need to move or bulk edit Azure DevOps and TFS data across projects, collections or organizations, and you have someone on the team who already knows the Azure DevOps object model. Do not adopt it as a general purpose bulk edit UI for a single project, or on a non-Windows machine, since the tools run on Windows only. Before you plan a migration, read the permissions documentation for your source and target, take a backup with the tool's own backup facility, and test the field and type mappings on a copy of a small project first, because the README is explicit that not all cases are supported.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. nkdAgility/azure-devops-migration-tools on GitHub
3. Project website
4. README
5. Releases