Move a project collection
Azure DevOps Server 2022 | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018
You can move a project collection from one deployment of Azure DevOps Server to another. For example:
- You have more than one deployment of Azure DevOps Server in your organization, and you want to move a collection to another deployment to better align with your business needs.
- You want to move the collection to a remote office that has its own deployment of Azure DevOps Server.
- You want to expand your deployment of Azure DevOps Server by adding another instance of SQL Server to it, and you want to distribute existing collections between the instances.
- You need to incrementally upgrade your deployment by detaching an individual project collection from a deployment of Azure DevOps Server running an earlier version, and then move it to a server running the current version of Azure DevOps Server. (One common reason for this is some teams may need to migrate to a newer version of Azure DevOps Server, while others must remain on an older version for tools or projects reasons.) In this scenario, you must also then upgrade each project within the collection by using the Configure Features wizard. For more information, see Configure features after an Azure DevOps Server upgrade. The Configure Features wizard has been deprecated for Azure DevOps Server 2019. You can only run the wizard on TFS 2018 and earlier versions. Projects defined on Azure DevOps Services update automatically with each service upgrade.
The steps to move a collection will depend on the particular configuration of the deployment that hosted the collection and the deployment to which you move it. For example, if you move a collection to a new domain, you will need to add users from that domain to the appropriate groups at the collection level and the project level.
Here's how to move an entire project collection. To move part of a collection, see Split a project collection.
Prerequisites
Before you start your move, make sure that you're an administrator on the servers and in the software used by both the deployment you're moving from, and the one you're moving to. If you're not an administrator, get added as one.
1. Detach the collection
Before you move a collection, first detach it from the deployment of Azure DevOps Server on which it is running. It's very important to not skip this step. When you detach a collection, all jobs and services are stopped, and then the collection database is stopped. In addition, the detach process copies over the collection-specific data from the configuration database and saves it as part of the project collection database. This configuration data is what allows the collection database to be attached to a different deployment of Azure DevOps Server. If that data is not present, you cannot attach the collection to any deployment of Azure DevOps Server except the one from which it originated.
Note
Detaching a collection prevents users from accessing any projects in that collection.
Open the administration console for Azure DevOps on the server that hosts the collection to move, and in Project Collections, highlight that collection.
On the General tab, select Detach Collection.
The Detach Project Collection Wizard opens.
(Optional) On the Provide a servicing message for the project collection page, in Servicing Message, provide a message for users who may try to connect to projects in this collection.
Select Next.
On the Review settings that will be used to detach project collection page, review the details.
To change any settings, select Previous. If they appear to be correct, select Verify.
When all the readiness checks have completed successfully, select Detach.
On the Monitor the project collection detach progress page, when all processes have completed, select Next.
(Optional) On the Review supplemental information for this project collection page, either select or note the location of the log file.
Select Close.
The project collection no longer appears in the list of collections in the administration console.
2. Back up the collection database
After you have detached the collection, back up its database to move it to the other server. To perform this task, use the tools that are provided with SQL Server.
- For information about this task, see Back up and restore databases in SQL Server and Create a backup schedule and plan. Be sure to select the version of SQL Server that matches your deployment.
Important
You can only restore a database to the same version or a more recent version of SQL Server. You can't restore a SQL Server database to an earlier version of the product
If your original deployment used the Enterprise or Datacenter editions of SQL Server, and you want to restore databases to a server running Standard edition, you must use a backup set that was made with SQL Server compression disabled. Unless you disable data compression, you will not be able to restore Enterprise or Datacenter edition databases to a server running Standard edition. To turn off compression, follow the steps in Disable SQL Server data compression in Azure DevOps databases.
3. Move the collection database
As part of moving the collection, you must restore, copy, or otherwise move the collection database to an instance of SQL Server that is configured to support the deployment of Azure DevOps Server to which you're moving the collection. You can select whichever method you prefer to move the database.
For more information about moving a database to another instance of SQL Server, see:
4. Attach the collection
After you restore the collection database, you can attach the collection to the preferred deployment of Azure DevOps Server. If the deployment you're moving to uses reporting, a reporting folder and default reports are built for the collection you're attaching as part of the process.
Open the administration console for Azure DevOps on the server that hosts the application tier for the deployment to which you're moving the collection.
Select Project Collections, and then select Attach Collection.
The Attach Project Collection Wizard opens.
On the Select the project collection database to attach page, in SQL Server Instance, provide the name of the server and the instance that hosts the collection database, if it is not already listed.
In the Databases list, select the collection database to attach, and then select Next.
On the Enter the project collection information page, provide a name for the collection in Name if one is not already present.
(Optional) In Description, provide a description of the collection.
Select Next.
On the Review settings that will be used to attach the project collection page, review the information.
To change any settings, select Previous. If all the settings are correct, select Verify.
When all the readiness checks have completed successfully, select Attach.
On the Monitor the project collection attach progress page, when all processes have completed, select Next.
(Optional) On the Review supplemental information for this project collection page, select or note the location of the log file.
Select Close.
The project collection appears in the list of collections in the administration console.
5. Configure the moved project collection
You can skip this procedure if you moved the collection in the same domain, and intend to use the same web application that previously supported the collection, and you want to allow access for the administrators of that collection to this deployment of Azure DevOps Server.
After you have moved a collection, update the web application and permission groups for that collection with the appropriate settings.
Configure the moved collection
Open each tab for the project collection and, if necessary, modify the settings to reflect the services and locations to match the locations of the resources on the current Azure DevOps Server. This is particularly important to do for reporting resources. If you see errors, make sure that your account has the permissions required for administrators of project collections, and that any other project collection administrators have been added as needed.
For information about this task, see Modify a project collection and Set administrator permissions for project collections.
6. Configure projects
You can skip this procedure if you moved the collection in the same domain and you want to allow access for the users of projects in that collection to this deployment of Azure DevOps Server.
After you configure administrators for the moved collection, either you or those administrators must add users and groups to the projects in that collection. Depending on your deployment, you may also need to configure permissions for those users in Reporting Services.
Add users to projects
- For information about this task, see Add users to projects.
Add resources to moved projects
- For more information about this task, see Configure resources to support projects.
Q & A
Q: My Azure DevOps Server deployment uses reporting. How do I move reports along with moving a collection?
A: First, you'll need to save or export any reports you want to move from the report server that supported the collection in its original deployment. Then you'll need to upload each report manually to the report server that will support the moved collection, which can be a lengthy process. Consider whether you want to upload all reports or whether a subset of reports will meet your business needs. You do not have to upload all reports or any reports, but only those reports that you upload will be available after the move process is completed.
You'll also need to rebuild the warehouse and analysis services cube on the original deployment after you've moved the collection, so the original deployment doesn't keep trying to build reports for a collection that is no longer there.
Move reports
Export or save the reports you want to move from the report server that supported the collection in its original deployment. For more information, see Export reports and Save reports.
Upload each report that you want to move to the appropriate folder on the report server that supports the collection in its new environment in Report Manager.
For more information, see Upload files to a folder.
In Report Manager, edit each report to change the data source to the new report server.
Rebuild the data warehouse and Analysis Services
Open the administration console for Azure DevOps.
In the navigation bar, select Reporting.
In Reporting, select Start Rebuild.
In the Rebuild the Warehouse and Analysis Services Databases dialog box, select OK.
Note
The warehouses will finish rebuilding and the data will finish repopulating after the Start Rebuild action completes. Depending on the size of your deployment and the amount of data, the entire process may take several hours to complete.
Q: How do I move a team project collection that includes deployment pools and/or deployment groups?
A: When you move the collection to another deployment, for each deployment pool in the source having a deployment group in the detached collection,
a new deployment pool is automatically provisioned in the target instance. In case of Azure DevOps Server 2019 or later, the name of automatically provisioned deployment pool is the same as in the source instance.
In prior versions, the deployment pool name is in the format <project name-deployment-group name>.
In case of conflicts, a random GUID is appended to the deployment pool name.
Once the move is complete:
- There is a possibility of multiple deployment pools being created. You can merge the duplicate pools using the TfsConfig command.
For example,
TfsConfig.exe deploymentpool /migrateDeploymentGroups /fromPool:<Source Pool Name> /toPool:<Target Pool Name> - You need to reconfigure the agents with the new deployment pool. Here is a sample deployment agent reconfiguration script for your reference.
Delete the Lab Management resources before moving the collection
- For information about how to remove all group hosts, library shares, and environments from a specified project collection, see TFSConfig Lab /Delete command with the /External option.
Configure Lab Management resources after moving the collection
Configure the application tier for Azure DevOps.
For more information, see Configure Lab Management for SCVMM environments.
Recreate the golden master virtual machines and templates in the new SCVMM and import virtual machines and templates into the project collection.
For more information, see Create and store virtual machines and templates ready for Lab Management.
Recreate the environments for each project.
For more information, see Create an SCVMM environment by using stored virtual machines and templates.
Q: How do I restrict access to select functions in a project?
A: Users who have permissions to access one project within a collection can view other projects within that collection, even if they don't have permissions to modify work items or perform other actions in that project. You can Grant or restrict access to select features and functions for creating or modifying select artifacts, as well as restrict them from seeing projects, by specifically creating groups and configuring restrictions on those groups.