Azure DevOps Migration Tools

The Azure DevOps Migration Tools allow you to bulk edit and migrate data between Team Projects on both Microsoft Team Foundation Server (TFS) and Azure DevOps Services. Take a look at the documentation to find out how. This project is published as code on GitHub as well as a Azure DevOps Migration Tools on Chocolatey.
Ask Questions on Stack Overflow: https://stackoverflow.com/questions/tagged/azure-devops-migration-tools
INFO: This tool was developed to support the scenarios below, and the edge cases that have been encountered by the 30+ contributors from around the Azure DevOps community. You should be comfortable with the TFS/Azure DevOps object model, as well as debugging code in Visual Studio. Community support is available through GitHub and StackOverflow; Paid support is available through our recommended consultants as well as our contributors and many DevOps consultants around the world.
What can you do with this tool?
- Migrate
Work Items
,TestPlans & Suits
,Teams
,Shared Queries
, &Pipelines
from oneTeam Project
to another - Migrate
Work Items
,TestPlans & Suits
,Teams
,Shared Queries
, &Pipelines
from oneOrganisation
to another - Bulk edit of
Work Items
accross an entireProject
.
What versions of Azure DevOps & TFS do you support?
- Work Item Migration Supports all versions of TFS 2013+ and all versions of Azure DevOps
- You can move from any Tfs/AzureDevOps source to any Tfs/AzureDevOps target.
- Process Template migration only supports XML based Projects
Typical Uses of this tool
- Merge many projects into a single project
- Split one project into many projects
- Assistance in changing Process Templates
- Bulk edit of Work Items
- Migration of Test Suites & Test Plans
- new Migration of Builds & Pipelines
- Migrate from one Language version of TFS / Azure Devops to another (new v9.0)
**NOTE: If you are able to migrate your entire Collection to Azure DevOps Services you should use Azure DevOps Migration Service from Microsoft. If you have a requirement to change Process Template then you will need to do that before you move t
Quick Links
- Video Overview
- Getting Started
- FAQ
- !preview v2 How To Migrate Things
- !preview v2 Reference
Extras
This is a preview version of both the documentation and the Azure DevOps Migration Tools.
Reference: A Deep Dive
- !preview v2 Reference
- !preview v2 Processors
- !preview v2 ProcessorEnrichers
- !preview v2 Endpoints
- !preview v2 EndpointEnrichers
External Walkthroughs and Reviews
- TFS 2017 Migration To VSTS with VSTS Sync Migrator from Mohamed Radwan
- Options migrating TFS to VSTS from Richard Fennell
- Migrating Test artifacts and all other work item types using the Azure DevOps from Gordon Beeming
Getting the Tools
There are two ways to get these tools:
- (recommended)Install from Chocolatey
- Download the latest release from GitHub and unzip
Getting Support
- Question on Stackoverflow - The first place to look for unsage, configuration, and general help is on Stackoverflow.
- Issues on Gitbub
Processors (v1 Architecture)
There are other processors that can be used to migrate, or process, different sorts of data in different ways. Which one is right for you depends on the situation at hand.
Most of these processors need to be run in order. If you try to migrate work items before you have migrated Area and Iterations then bang you need to go back.
Processor | Status | Target | Usage |
---|---|---|---|
WorkItemMigrationConfig | ready | Work Items | Migrates either tip or history of work items with Links & Attachments based on a query with field mappings |
TfsTeamSettingsProcessor | preview | Teams | Migrates Teams and Team Settings |
TfsAreaAndIterationProcessor | preview | Area & Iterations | Migrates Nodes before run |
WorkItemDelete | ready | Work Items | Bulk delete of work items WARNING DANGEROUS |
WorkItemUpdate | ready | Work Items | Bulk update of Work Items based on a query and field mappings |
TfsSharedQueryProcessor | preview | Shared Queries | Moved Shared Queries best effort |
TestVariablesMigration | Beta | Suites & Plans | Migrates Test Variables |
TestConfigurationsMigration | Beta | Suites & Plans | Migrates Test configurations |
TestPlansAndSuitesMigration | Beta | Suites & Plans | Rebuilds Suits and plans for Test Cases migrated using the WorkItemMigration |
ImportProfilePicture & ExportProfilePictureFromAD | Beta | Profiles | Downloads corporate images and updates TFS/Azure DevOps profiles |
WorkItemUpdateAreasAsTags | Beta | Work Items | Adds tags to work items to reflect area paths on source system |
TestRunsMigration | Alpha | Suits & Plans | Migrates the history of Test Runs |
Processors (v2 Architecture) [ PREVIEW ]
These are experimental processors that should replace those above. We are intersted in feedback of the new format of the config, as well as the functionality.
The new processor configuration is designed to allow the Migration Tools to support diferent Source and targets than just TFS/Azure DevOps, and we moved the Endpoints to the processor to allow both Object Model & REST in different processors.
Processor | Status | Target | Usage |
---|---|---|---|
WorkItemTrackingProcessor | Alpha | Work Items | Migrates either tip or history of work items with Links & Attachments based on a query with field mappings |
TfsTeamSettingsProcessor | preview | Teams | Migrates Teams and Team Settings |
TfsSharedQueryProcessor | preview | Shared Queries | Moved Shared Queries best effort |
Field Maps
By default, when you are moving from source to target the system will map all of the fields that exist in source to the same field in the target. This is the behaviour if the FieldMaps section is not present in the configuration file.
However sometimes you want to move data to another field, or use a regex to parse out just the bits that you want. To help we have built a number of mapping tools that should give you the versatility you need.
- FieldtoFieldMap - Just want to map one field to another? This is the one for you.
- FieldtoFieldMultiMap - Allows you to create a list of one to one field maps.
- FieldMergeMap - Ever wanted to merge two or three fields? This mapping will let you do just that.
- FieldBlankMap - Allows you to set an already populated field to empty
- FieldtoTagMap - Want to take a field and convert its value to a tag? Done…
- FieldValueMap - Need to map not just the field but also values? This is the default value mapper.
- FieldValuetoTagMap - Need to create a Tag based on a field value? Just create a regex match and choose how to populate the target.
- RegexFieldMap - I just need that bit of a field… need to send “2016.2” to two fields, one for year and one for release? Done.
- TreeToTagMap - Need to clear out those nasty Area tree hierarchies? This creates Tags for each node in the Area Path…
Code (TFVC)
There are no good tools for migrating TFVC code. All of them suffer from “time-dilation” as one can’t control the dates of the Check-ins. While you can use tools like TaskTop, TFS Integration Tools, or others there is no support. We prefer to recommend that you use Git-TFS and migrate from TFVC to Git with full history and branches. If your resulting repository is too large we recommend creating a full clone of TFVC for posterity, and then create a limited branch clone with limited history for work.
Code (Git)
When moving Git repos between Projects and Accounts you are able to maintain full history. However you will need to have all of the links to
- FixGitCommitLinks - (obsolete) [this is now fixed on the fly if git is migrated first) Allows you to fix the migrated Git commit hooks (and thus external links) to point to the new repository in the target project. If the source and target repository names are the same, this will work out of the box. If the target repository has a different name, you can specify that name via the “TargetRepository” property.
Build & Releases
When you import a build or release definition into VSTS you need to fill out some of the data to allow that new definition to be saved. Things like connections and other require fields usually don’t have matching GUIDS and need manual intervention. For builds & Releases we recommend that you use the built in Export/Import tools provided in the UI to move then to a new Team Project.
Why does this exist
The main migration tool for TFS has always been the TFS Integration Tools which is sadly no longer supported. Indeed it only loosely supported versions of TFS after 2010 and had a lot of bugs. It was very difficult to configure and run. This tool hopes to solve some of that by providing support for TFS 2015 and Visual Studio Team Services (VSTS).
It solves:
- Supports all currently supported version of TFS
- Supports Azure DevOps Services
- Migrates work items from one instance of TFS or Azure DevOps to another
- Bulk edits fields in place for both TFS and Azure DevOps Services
- Being able to migrate Test Plans an Suits from one Team Project to another
- Being able to migrate Teams from one Team Project to another
Contributing
If you wish to contribute then feel free to fork this repository and submit a pull request. If you would like to join the team please contact.
This project is primarily managed and maintained on Visual Studio Team Services and code checked into MASTER is automatically synched between VSTS and GitHub. There is no hidden published code, but not all branches are published.
If you want to sync your GitHub repository then check out Open-source with VSTS or TFS and Github for better DevOps .
Events for the Team:
- Weekly Architectural Review - Thursday 2100 GMT
If you want to be added to the community Team then please fill out this form and request access
Support
You can get free support from the community here and on social media on a best effort basis if folks are available. If you are looking for paid support there are a number of consultants that contribute to this project and that are experts in this type of work:
- Martin Hinshelwood, naked Agility Ltd - @MrHinsh is the founder of the Azure DevOps Migration Tools is available worldwide to help organisations plan and enact their migration efforts. You can contact him through naked Agility Ltd..
- Wes MacDonald, LIKE 10 INC. - @wesmacdonald is a DevOps Consultant located in Toronto, Canada. You can reach out to him via LIKE 10 INC..
- Ove Bastiansen - @ovebastiansen is a DevOps consultant living in Oslo, Norway, but working worldwide in todays remote friendly world. You can reach him via his GitHub profile https://github.com/ovebastiansen.
- Gordon Beeming - @DevStarOps is a DevOps Specialist in Durban, South Africa working at Derivco. You can reach him via his profile page that links to all social media.
- others coming soon
These tools are build by naked Agility Limited’s DevOps & Agility consultants to do real world migrations on a daily basis. We always work in Azure DevOps Services on https://dev.azure.com/nkdagility/migration-tools/ with code in GitHub and publish as a chocolatey package that pulls from GitGub Releases.
Team Work Items | Azure Boards |
Public Issues | GitHub Issues |
Builds & Releases | Azure Pipelines |
Releases Output | Github Releases |
Documentation | Github Pages |
Watch the Video Overview to get you started in 30 minutes. This tool is complicated and its not always easy to discover what you need to do.
FAQ
Check out the FAQ pages
Terms
naked Agility Limited & our contributors creates and maintains the “Azure DevOps Migration Tools” project under its terms of business and allows full access to the source code for customers and the general public.