Moving to Azure DevOps is on many roadmaps but rarely on a calendar. The reason is usually not the tooling. It is three things that are hard to decide. The first is how long the teams will be down. The second is what happens to years of history. The third is who owns the migration.
A checklist answers these questions by breaking the work into clear steps you can check off. It helps you avoid missed dependencies, keeps responsibilities clear, and gives you proof that each step was done.
Here is the full process in four phases.
Phase 1: Plan
Planning sets the scope and the approach before any data moves.
Define the purpose and scope. Write down why you are migrating. Common reasons are moving off TFS or Azure DevOps Server to Azure DevOps Services, consolidating projects or organizations, retiring old infrastructure, and standardizing process across teams.
Then define the scope. List the projects that will move, the data to migrate, the data to archive, the source and target environments, the users and teams affected, the integrations involved, the expected downtime, and any compliance or retention rules.
Set success criteria before you start. For example: all approved projects migrated, work item history preserved, repositories available, and access validated.
Inventory the source environment. You cannot estimate effort or validate results for items you have not counted. Record the following:
- Projects: active, archived, and inactive
- Work items: epics, features, user stories, product backlog items, tasks, bugs, and issues
- Test assets: plans, suites, cases, configurations, runs, and results
- Source control: Git repositories, TFVC, changesets, branches, pull requests, and branch policies
- Pipelines: build, release, and YAML pipelines, service connections, and variable groups
- Collaboration and reporting: wikis, dashboards, queries, widgets, attachments, and comments
For each item, note the quantity, the owner, the business purpose, and the migration priority.
Decide what not to migrate. Migration is a good time to remove data that no longer serves a business purpose. Review each project and mark it as migrate, archive, keep read-only, or exclude. Good candidates to archive are obsolete projects, duplicate repositories, inactive accounts, outdated dashboards, and unused pipelines. Keep a record of what you excluded so users can find it later and audits are supported.
Choose a strategy. Pick an approach based on the source, the target, the project structure, and the downtime you can accept.
| Approach | When it fits |
|---|---|
| Big-bang | All approved data moves in one planned cutover |
| Phased | Projects move in separate groups |
| Pilot | You need to test the approach before production |
| Live or continuous | Teams keep working while source and target stay in sync |
Phase 2: Prepare
Preparation confirms that the environments, the data, and the dependencies are ready.
Ready both environments. Check access, permissions, service accounts, network connectivity, storage, versions, organization and project structure, naming standards, extensions, and authentication settings. The target should be fully configured before any data is loaded.
Map customizations. Most long-running Azure DevOps and TFS projects contain custom work item types, fields, workflows, and rules. Document them. Then build a mapping document that shows how each source configuration maps to the target. Doing this well avoids a second migration run.
Validate identities and permissions early. User mapping is often left until after migration, and that usually means a re-run. Map your users before you move data. Include active users, inactive users, Microsoft Entra ID identities, service accounts, administrators, and security groups. Then validate ownership, access levels, and notification recipients. If a user is not mapped, the tool records the migrating account as the author instead. You keep the history, but you lose the record of who did the work.
Assess integrations. Document every system connected to Azure DevOps, such as Jira, GitHub, Jenkins, ServiceNow, SonarQube, and Microsoft Teams. For each one, record the purpose, the authentication method, the endpoints, the owner, and the data exchanged. Decide whether each integration will continue, be replaced, or be retired.
Clean the data. Fix data problems before you migrate, not after. Resolve duplicate work items, broken links, missing attachments, invalid user references, and obsolete fields. Clean source data becomes clean target data and reduces the time spent on validation.
Back up and verify recovery. Back up the data you need for recovery and validation. Depending on the environment, this includes work items, repositories, TFVC changesets, attachments, wiki content, dashboards, queries, and pipeline configurations. Confirm that the backup can be restored. Name the recovery owner and the recovery steps before the production migration.
Run a pilot. Run a pilot migration on a representative project before production. Choose a project that contains the work item types, repositories, tests, pipelines, and customizations in your production scope. Use the pilot to validate field mappings, test user mappings, measure the migration duration, review the reports, find errors, and refine the cutover plan. Use a real project, not a sandbox, because sandbox data rarely contains the custom fields and edge cases of real projects.
Phase 3: Execute
Execution moves the approved data according to the plan.
Finalize mappings. Confirm the final mappings for work item types, custom fields, users, states, iterations, area paths, tags, links, relationships, repositories, test assets, and pipeline configurations. Decide in advance how conflicts, missing values, and unsupported configurations will be handled.
Communicate the cutover. Tell affected users before migration begins. Share the date and time, the maintenance window, the restrictions, the systems affected, the actions users need to take, the validation period, and the support contacts. Clear communication stops people from making untracked changes while the migration runs.
Decide how source changes are handled. State whether users can create or update work items, whether code commits are restricted, and whether pipelines stay active during the migration. Define how late changes are captured and synchronized. This plan should match your migration strategy.
Run it and watch it. Run the production migration in the approved sequence. Monitor progress, review logs, check performance, track connectivity, record failed items, and keep migration records. For a phased migration, validate each group before starting the next. Look for one property in your tooling: a single item that fails should be logged and retried from the last sync point, not stop the whole run.
Phase 4: Validate, stabilize, and close
Validation confirms that the new environment is usable and that the migrated data is complete and connected. Teams often rush this phase. It is the phase that decides whether people trust the result.
Validate the data. Counts are a first check, not proof. Compare the source and target on work item counts, types, states, tags, and assignments. Then open actual items and check the details. For history, check comments, change history, user details, and timestamps. For attachments, check that files are available, links are correct, and inline images still display. Also validate test assets, source control, and reporting assets. Use automated comparison together with manual checks of sample records.
Verify traceability. Counts confirm that records arrived. Traceability confirms that the links between records survived. Check the links across the chain:
Requirements → user stories → tasks → source code → bugs → test cases → releases
Links that still point back to the source system are a common migration failure. They look fine until someone clicks one later and reaches a server that no longer exists.
Run user acceptance testing. Ask a lead from each affected team to test their own project. They should create and update work items, run saved queries, view dashboards, run test plans, trigger pipelines, access repositories, and check permissions. Team leads know what correct looks like for their own data.
Validate integrations, then monitor go-live. Re-test the connected systems and automations. Check service connections, webhooks, API integrations, automation rules, and pipeline triggers. After users move to the new environment, monitor performance, permission errors, pipeline failures, synchronization issues, and any problems users report.
Retire the legacy environment. Retire the source environment only after validation and acceptance are complete. Before retirement, confirm that all approved data was migrated, verify compliance and audit requirements, retain the backups, and notify users. Keep read-only access for a set period if your policy requires it.
Capture lessons learned. Review the migration when it is done. Document what worked, what went wrong, the root causes, the duration, and the improvements for next time. Store the final inventory, the mapping documents, the reports, and the approvals in a place the team can find.
The mistakes worth avoiding
| Common mistake | Better approach |
|---|---|
| Starting without a complete inventory | Record projects, assets, owners, and dependencies first |
| Migrating every piece of historical data | Archive or exclude what no longer serves a purpose |
| Ignoring customizations | Document fields, workflows, and rules before mapping |
| Skipping identity mapping | Build and validate a user and permission mapping plan |
| Leaving integrations until after migration | Assess each one and define its required changes |
| Skipping backup verification | Test the recovery process before production |
| Running production without a pilot | Validate the approach on a representative project |
| Treating execution as the finish line | Validate data, traceability, integrations, and access |
| Not communicating the cutover | Share timing, restrictions, and support contacts early |
Where a migration tool fits
Some parts of this process are hard to do by hand. Preserving full revision history, comments, attachments, user mentions, and the links between work items is one. Mapping users and custom fields is another. Migrating while teams keep working is a third, along with recovering a failed run from the last sync point instead of starting again.
A dedicated migration tool handles these parts. OM4ADO (OpsHub Migrator for Microsoft Azure DevOps) does this for Team Foundation Server and Azure DevOps migrations. It provides configurable mappings, trial runs, migration reports, and failure management. The entities it can migrate depend on the source, the target, and the edition, so confirm the supported scope before production.
This is a shorter version of the full guide. The complete 25-step checklist, with the detail for each step, is on the original post.
Top comments (0)