Azure DevOps Migration Tools
Article
11 minutes to read
2024-12-04 17:20:47 +0000
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 Winget package a nkdAgility.AzureDevOpsMigrationTools.
Compatability
These tools run on Windows and support connecting to Team Foundation Server 2013+, Azure DevOps Server, & Azure DevOps Services. They support both hosted and on-premise instances and can move data between any two.
- Supports all versions of TFS 2013+ and all versions of Azure DevOps.
- You can migrate from any TFS/Azure DevOps source to any TFS/Azure DevOps target.
What do you get?
- Move Work Items, Test Plans & Suits, and Pipelines between projects, collections, and even organizations.
- Merge multiple projects into a single project even from different organizations.
- Split one project into several projects even between projects, collections, and even organizations.
- Change Process process from Agile to Scrum or any other template.
- Bulk edit Work Items.
What does this tool do?
For the most part we support moving data between ((Azure DevOps Server | Team Foundation Server | Azure DevOps Services) <=> (Azure DevOps Server | Team Foundation Server | Azure DevOps Services)) for any version greater than 2013.
Work Items(including links and attachments) with custom mappings for fields and types- Copy Work Items between locations with history
- Bulk Edit in place of Work Items (Great for cleaning up data, process template changes)
- Optionaly includes
Teams,Shared Queries
Test Plans & Suites- Copy Test Plans & Suites between locations
- Includes
Configurations,Shared Steps,Shared Parameters
Pipelines- Copy Pipelines between locations
- excludes XAML & Classic Builds & Release
Processes- Copy Processes between locations
Note: ‘Locations’ includes Projects, Collections, Organizations
Important: This tool is intended for experienced users familiar with TFS/Azure DevOps object models and debugging in Visual Studio. It was developed by 100+ contributors from the Azure DevOps community to handle various scenarios and edge cases. Not all cases are supported.
Support Options: Community support is available on GitHub. For paid support, consider our Azure DevOps Migration Services.
Quick Links
- Installation
- Permissions
- Getting Started
- Configuration Reference
- FAQ
- Support
- Community Support
- Commercial Support
The documentation for the preview is on Preview]
External Walkthroughs and Reviews
- TFS 2017 Migration To Azure DevOps with Azure DevOps Sync Migrator from Mohamed Radwan
- Options migrating TFS to Azure DevOps from Richard Fennell
- Migrating Test artifacts and all other work item types using the Azure DevOps from Gordon Beeming
## Metrics (v16+ experimental)
These metrics come directly from Custo Metrics in Application Insights and are updated every 10 minutes. They are experimental and may not be accurate yet… once I get more data Ill tweek both the collection and rendering.
| Metric | Category | Type | All | v16 | Notes |
|---|---|---|---|---|---|
| WorkItemMetrics | Work Items | Count |  |
 |
This counts the number of work items processed |
| WorkItemMetrics | Work Items | Ave |  |
 |
the average amount of time a work item takes to process |
| WorkItemMetrics | Revisions | Count |  |
 |
the total number of revisions processed |
| WorkItemMetrics | Revisions | Ave |  |
 |
the average number of revisions per work item |
This tool uses OpenTelemetery to collect metrics and logs, and Application Insights to store and analyse them. Exceptions are also sent to Elmah.io for analysis and improvement.
Some Data from the last 30 days (v15- as of 06/04/2023)
| Catagory | Metric | Notes |
|---|---|---|
| Work Item Revisions | 14m | A single Work Item may have many revisions that we need to migrate |
| Average Work item Migration Time | 35s | Work Item (inlcudes all revisions, links, and attachements for the work item) |
| RelatedLinkCount | 5m | Each work item may have many links or none. |
| Git Commit Links | 480k | |
| Attachments | 252.37k | Total number of attachments migrated |
| Test Suits | 52k | total suits migrated |
| Test Cases Mapped | 800k | Total test cases mapped into Suits |
| Migration Run Ave | 14 minutes | Includes dry-runs as well. |
| Migration Run Total | 19bn Seconds | Thats 316m hours or 13m days of run time in the last 30 days. |
Processors
| Name | Status | Target | Usage |
| AzureDevOpsPipelineProcessor | Beta | Pipelines | Azure DevOps Processor that migrates Taskgroups, Build- and Release Pipelines. |
| KeepOutboundLinkTargetProcessor | missing XML code comments | missing XML code comments | missing XML code comments |
| OutboundLinkCheckingProcessor | missing XML code comments | missing XML code comments | missing XML code comments |
| ProcessDefinitionProcessor | Beta | Pipelines | Process definition processor used to keep processes between two orgs in sync |
| TfsExportProfilePictureFromADProcessor | alpha | Profiles | Downloads corporate images and updates TFS/Azure DevOps profiles |
| TfsExportUsersForMappingProcessor | ready | Work Items | ExportUsersForMappingContext is a tool used to create a starter mapping file for users between the source and target systems. Use |
| TfsImportProfilePictureProcessor | alpha | Profiles | Downloads corporate images and updates TFS/Azure DevOps profiles |
| TfsSharedQueryProcessor | Beta | Queries | The TfsSharedQueryProcessor enabled you to migrate queries from one locatio nto another. |
| TfsTeamSettingsProcessor | Beta | Teams | Native TFS Processor, does not work with any other Endpoints. |
| TfsTestConfigurationsMigrationProcessor | Beta | Suites & Plans | This processor can migrate |
| TfsTestPlansAndSuitesMigrationProcessor | Beta | Suites & Plans | Rebuilds Suits and plans for Test Cases migrated using the WorkItemMigration |
| TfsTestVariablesMigrationProcessor | Beta | Suites & Plans | This processor can migrate test variables that are defined in the test plans / suites. This must run before |
| TfsWorkItemBulkEditProcessor | missing XML code comments | WorkItem | This processor allows you to make changes in place where we load from teh Target and update the Target. This is used for bulk updates with the most common reason being a process template change. |
| TfsWorkItemDeleteProcessor | ready | WorkItem | The |
| TfsWorkItemMigrationProcessor | ready | Work Items | WorkItemMigrationConfig is the main processor used to Migrate Work Items, Links, and Attachments. Use |
| TfsWorkItemOverwriteAreasAsTagsProcessor | Beta | Work Item | A common issue with older TFS/Azure DevOps instances is the proliferation of |
| TfsWorkItemOverwriteProcessor | preview | Work Items | Reapply field mappings after a migration. Does not migtate Work Items, only reapplied changes to filed mappings. |
| WorkItemTrackingProcessor | missing XML code comments | missing XML code comments | This processor is intended, with the aid of ProcessorEnrichers, to allow the migration of Work Items between two Endpoints. |
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 behavior 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.
| Name | Status | Target | Usage |
| FieldClearMap | missing XML code comments | missing XML code comments | missing XML code comments |
| FieldLiteralMap | missing XML code comments | missing XML code comments | missing XML code comments |
| FieldMergeMap | missing XML code comments | missing XML code comments | missing XML code comments |
| FieldSkipMap | missing XML code comments | missing XML code comments | missing XML code comments |
| FieldToFieldMap | missing XML code comments | missing XML code comments | missing XML code comments |
| FieldToFieldMultiMap | missing XML code comments | missing XML code comments | missing XML code comments |
| FieldToTagFieldMap | missing XML code comments | missing XML code comments | missing XML code comments |
| FieldValueMap | missing XML code comments | missing XML code comments | missing XML code comments |
| MultiValueConditionalMap | missing XML code comments | missing XML code comments | missing XML code comments |
| RegexFieldMap | missing XML code comments | missing XML code comments | missing XML code comments |
| TreeToTagFieldMap | missing XML code comments | missing XML code comments | missing XML code comments |
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 VAzure DevOps 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 Azure DevOps or TFS and Github for better DevOps .
Primary Contributors & Consultants
- 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.
- Richard Hundhausen - @rhundhausen is an Azure DevOps consultant living in the United States and working at Accentient
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.
