How do you move an Azure DevOps project between organizations, and what are the limitations?

Think of moving an Azure DevOps project between organizations like transferring a department from one company to another. The employees (repositories) can physically move, but their badges (Service Connections), desk configurations (variable groups), and security clearances (permissions) are all tied to the original company's systems and must be recreated from scratch in the new company. The HR records (work item history) can be photocopied but the originals stay behind. There is no 'transfer department' button because the two companies have completely different administrative systems, identity providers, and security boundaries. The migration requires systematically moving each component using the appropriate tool for each type of data.

The limitation exists because Azure DevOps organizations are the top-level security and identity boundary. Each organization has its own Azure Active Directory tenant connection, billing subscription, user licenses, and administrative policies. Projects within an organization share these organizational settings. Moving between organizations means crossing this boundary, which breaks all identity references, permission assignments, and resource connections. Microsoft provides collection-level migration (the Data Migration Tool discussed earlier) which moves everything at once, but there is no supported tool for moving a single project from a multi-project organization to a different organization while leaving other projects behind.

Git repositories are the simplest component to migrate. Azure DevOps supports importing Git repositories from any accessible URL, preserving all branches, tags, and commit history. You can use az repos import to clone a repository from the source organization into the target. If the source repository is private, you provide a PAT with read access. Large File Storage (LFS) objects require additional steps: you must ensure LFS objects are pushed to the new remote after the main repository import. For TFVC repositories, conversion to Git using git-tfs is recommended before migration, as TFVC repository migration between organizations is not supported without the Data Migration Tool.

Work items are the most complex component because Azure DevOps does not have a native bulk export/import that preserves full revision history between organizations. The Azure DevOps Migration Tools by nkdAgility (formerly Martin Hinshelwood's tools) is the community-standard solution. It connects to both source and target organizations via REST API, reads work items with full history, maps fields and states between different process templates, and creates corresponding work items in the target with preserved timestamps and authors (using bypassRules). The tool handles parent-child relationships, links between work items, attachments, and area/iteration path structures. Without this tool, you are limited to CSV export/import which loses all history and relationships.

Pipelines, Service Connections, and organizational resources do not migrate and must be manually recreated. Pipeline YAML files committed to repositories transfer automatically with the repo, but the pipeline registration (triggers, settings, permissions) must be recreated. Service Connections contain credentials specific to the source organization's service principal and cannot be exported. Variable groups, agent pools, environments with approval checks, and library assets all require manual recreation. This is often the most time-consuming part of project migration because it requires knowledge of every integration point the project uses.

The production gotcha is underestimating the work item migration complexity and the loss of non-transferable data. Work item IDs change during migration (the target gets new sequential IDs), breaking external references from documentation, emails, and chat messages that reference work items by number. Teams must create a mapping table from old IDs to new IDs and update documentation accordingly. Another critical limitation: build and release history does not migrate. The target organization starts with no deployment history, which impacts compliance teams that need continuous audit trails. Test Plans with test cases, test suites, and test results also require the migration tools and significant effort to transfer correctly. Teams should document all of these limitations and get stakeholder acceptance before beginning the migration.