How to Migrate Your TFS Project to Azure DevOpsMigrating a Team Foundation Server (TFS) project to Azure DevOps can modernize your development workflow, enable cloud-hosted services, and simplify collaboration. This guide walks through planning, preparation, migration approaches, step-by-step execution, verification, and post-migration tasks to ensure a smooth transition.
Why migrate from TFS to Azure DevOps?
- Modern platform and cloud features: Azure DevOps offers hosted build and release pipelines, integrated artifact feeds, and hosted agents.
- Scalability and maintenance: Microsoft manages infrastructure for Azure DevOps Services, reducing the burden on your ops team.
- Continuous innovation: Frequent updates and a richer ecosystem of extensions and integrations.
- Improved collaboration: Web-based boards, pull requests, and code reviews with more modern UX.
1. Pre-migration planning
Assess your current TFS environment
- Inventory TFS version(s), server configuration, SQL Server version, and collection structure.
- List team projects, repositories (TFVC and Git), work item types, customizations (process templates, custom fields, workflows), build/release definitions, test plans, and artifacts.
- Identify third-party integrations and service hooks.
Define migration goals and scope
- Decide whether to migrate entire collections or selective team projects.
- Choose target: Azure DevOps Services (cloud) or Azure DevOps Server (on-premises). This guide focuses on Azure DevOps Services but many steps apply to Azure DevOps Server.
- Determine which assets to migrate: source code (TFVC or Git), work items, history, builds, releases, test artifacts, and attachments.
- Set success criteria: data fidelity, preserved history, CI/CD continuity, minimal downtime.
Choose migration approach
- In-place upgrade and migration using Microsoft tools (recommended path for many).
- Partial/manual migration (selective repos, fresh work items).
- Migration using third-party tools for complex TFVC histories or giant attachments.
- Consider a phased migration to reduce risk (e.g., code first, then work items, then builds).
2. Prepare your environment
Clean up TFS
- Archive or delete obsolete projects and branches to reduce migration complexity.
- Resolve outstanding work items, or decide to migrate only active items.
- Consolidate repositories if possible.
Backup and snapshot
- Create full backups of TFS databases and SQL Server.
- Take a snapshot of build servers, agent pools, and configuration as a rollback point.
Update TFS (if needed)
- If on an older TFS version, upgrade to a supported version for migration compatibility. Microsoft’s migration tools and documented paths often require recent versions; check Microsoft’s compatibility guidance.
Prepare Azure DevOps organization
- Create an Azure DevOps organization (for Services) or provision Azure DevOps Server (for on-prem).
- Configure billing, security policies, and licensing.
- Plan and create teams, projects, and permissions mirroring TFS structure where appropriate.
3. Migrate source code
TFVC to Azure DevOps (TFVC or Git)
- Option A — Migrate TFVC to TFVC in Azure DevOps Server: use the TFS database attach method when moving to Azure DevOps Server.
- Option B — Migrate TFVC to Git (recommended for modern workflows):
- Use git-tfs or git-tf to convert TFVC history to Git commits. git-tfs preserves changesets as commits and can migrate branches and history.
- For large histories, consider a partial history import (e.g., last N years) to limit repository size.
- After conversion, push converted Git repos to Azure Repos.
- Validate branches, tags, and commit authorship (map TFVC users to Git users).
Example git-tfs commands:
git tfs clone http://tfs:8080/tfs/DefaultCollection $/Path/To/Project --branches=all # After review: git remote add origin https://dev.azure.com/yourOrg/yourProject/_git/yourRepo git push -u origin --all git push origin --tags Git to Azure Repos
- For existing Git repos hosted in TFS, add the Azure Repos remote and push.
- Use git-filter-repo or BFG to remove large files or sensitive data before pushing.
4. Migrate work items and history
Options for work item migration
- Azure DevOps Migration Tools (formerly VSTS Sync Migrator): community-driven tool suitable for migrating work items, area/iteration paths, history, links, and attachments. Highly configurable but requires mapping work item types and field transformations.
- Microsoft Excel + REST API or Bulk Import: suitable for smaller sets of work items or selective migration.
- Commercial tools (e.g., OpsHub, TaskTop): offer more polished experiences and support for complex mappings, but may cost money.
Mapping considerations
- Map process templates: TFS process (on-prem XML-based) vs. Azure DevOps process models (Inherited, Hosted XML, or Agile/Scrum/CMMI). Choose an equivalent process or create an inherited process and custom fields to match behavior.
- Map area and iteration paths; preserve cadence and team assignments.
- Preserve links between work items, commits, and pull requests where possible.
- Migrate attachments and history if auditability is required — note this increases migration time and storage.
Example: Azure DevOps Migration Tools
- Configure configuration JSON to map source/target projects, field mappings, and processors for attachments and links.
- Run work item migration in stages: initial bulk migration, validation, then final cutover.
5. Migrate builds, releases, and pipelines
Classic build/release definitions
- Classic XAML builds or legacy builds need manual recreation in Azure Pipelines. Export definitions where possible then recreate as YAML pipelines.
- For Classic Release Definitions, recreate as YAML multi-stage pipelines or use classic pipelines as a stop-gap.
Recommended: move to YAML pipelines
- Convert build and release processes to YAML for versioning with code and easier reproducibility.
- Use Microsoft documentation and pipeline templates to rebuild CI/CD flows.
- Migrate pipeline variables, secrets (move to Azure Key Vault or pipeline variable groups), and service connections.
Agents and service connections
- Reconfigure self-hosted agents or use Microsoft-hosted agents.
- Recreate service connections (Docker registries, Azure subscriptions, NuGet feeds).
6. Migrate test plans and artifacts
- Test Plans migration is supported by some third-party tools and the Azure Test Plans REST API. Evaluate whether to migrate test cases, test suites, and test runs or to archive them.
- Export automated test results integration into pipelines.
7. Cutover strategy and DNS/redirects
- Plan a downtime window if using database-attach methods or if you must ensure no data changes during cutover.
- Communicate to stakeholders: freeze source commits at a cutoff time, document final synchronization steps.
- Perform final synchronization of code and work items after freeze to capture last-minute changes.
- Switch build agents and update external integrations (chat ops, CI badges, deployment endpoints).
8. Validation and verification
- Verify repository histories, branch count, tags, and file integrity.
- Validate work item counts, field mappings, attachments, and links.
- Run CI builds and deployments to confirm pipeline functionality.
- Ask teams to perform user acceptance testing: create work items, push code, run PRs, and test pipelines.
9. Post-migration tasks
- Decommission or repurpose TFS servers after confirming successful migration and backups.
- Train teams on Azure DevOps features and workflows (YAML, pull requests, boards).
- Update documentation, scripts, and automation to use new endpoints and service connections.
- Implement governance: policies, branch protections, required reviewers, and retention policies.
- Monitor usage and costs (if using Azure DevOps Services).
10. Common pitfalls and troubleshooting
- Large TFVC histories causing slow conversions — mitigate by archiving old history or partial import.
- Mismatched user identity mappings — prepare user map file beforehand.
- Missing custom process fields — create equivalent fields in Azure DevOps and map them.
- Build pipeline incompatibilities — incremental testing and conversion to YAML reduces surprises.
- Third-party integrations breaking — inventory and reconfigure integrations early.
Checklist (summary)
- Inventory TFS assets and customizations.
- Choose migration scope and target (Services vs Server).
- Clean up and backup TFS.
- Convert/migrate source code (TFVC -> Git recommended).
- Migrate work items with mappings and preserve history/attachments as needed.
- Recreate or convert build/release pipelines (prefer YAML).
- Migrate test plans if required.
- Plan cutover, perform final sync, and validate.
- Decommission old servers, train users, and enforce governance.
Migrating from TFS to Azure DevOps is a significant project but delivers long-term benefits in workflow modernization, scalability, and collaboration. With careful planning, staged execution, and thorough validation, you can minimize disruption and preserve critical project history.
Leave a Reply