Split a project collection

Article
04/05/2022

Azure DevOps Server 2022 | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018

As your business changes, you may want to split a single project collection into multiple project collections. For example:

You want the projects in a collection to align with business units in your organization, and the projects in the collection are now owned by separate units.
You upgraded from an earlier version of Azure DevOps Server, you have only one collection, and you want to organize your projects into separate collections for security or business alignment reasons.
You want to change ownership of some of the projects in the collection to a remote office that has its own deployment of Azure DevOps Server. This scenario requires that you first split a collection and then move one of the resulting collections to the remote office deployment.

Note

The procedures in this article support only splitting a project collection. To move a collection after you split it, see Move a project collection.

To split a project collection, follow these steps:

Prepare to split the collection
1. Detach the collection
2. Back up the collection database
Split the collection
Configure the split collections
1. Configure Users and Groups for the Split Project Collections
2. Configure users and groups for projects in the collections

Before you begin

Make sure that you're an administrator on the servers and in SQL Server and Azure DevOps Server. If you're not an administrator, get added as one.

1-a. Detach the collection

First detach the collection from the deployment of Azure DevOps Server on which it is running. Detaching a collection stops all jobs and services as well as the collection database itself. 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.

Detach a project collection

Open the administration console for Azure DevOps on the server that hosts the collection to split.
Select Project Collections, and in the list of collections, select the collection to split.

In this example, the administrator chooses TestProjects.

Tip

The default name for a project collection is DefaultCollection. If you are splitting this database, make sure to give the second collection a different name, because this is the default choice at connection.
On the General tab, select Stop Collection.

The Project Collection Status Reason dialog box opens. The text you enter will be displayed to your users. Select Stop, and wait for the collection to stop. When it is stopped, its status will show as Offline.
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.
On the Review settings that will be used to detach project collection page, review the details. To change any settings, select Previous. If they are 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, select or note the location of the log file, and then close the wizard.

The project collection no longer appears in the list of collections in the administration console.

1-b. Back up the collection database

After you have detached the collection, you must back up its database before you can restore a copy to the server with a different name. That copy will become the database for the part of the original collection that you want to split into another collection. To perform this task, use the tools that are provided with SQL Server.

Back up database

Back up a collection database

For information about how to manually back up and restore individual databases, 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

If your original deployment used the Enterprise or Datacenter editions of SQL Server, and you want to restore the database that you want to split 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 successfully 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.

2-a. Restore the collection database

When you split a collection, you must restore the backup of the collection database to an instance of SQL Server that is configured to support the deployment of Azure DevOps Server. When you restore the database, you must give it a different name from the name of the original collection database.

Tip

The steps below give a general overview of how to restore a project collection database in SQL Server 2012 using SQL Server Management Studio. For more information about how to manually back up and restore individual databases, see Back up and restore databases in SQL Server. Be sure to select the version of SQL Server that matches your deployment.

Restore the collection database with a new name

Open SQL Server Management Studio and connect to the instance that hosts the database for the project collection to split.
In Object Explorer, expand Databases, open the sub-menu for the database to split, and then select Tasks, select Restore, and then select Database.

The Restore Database window opens on the General page.
In Source, make sure that the project collection database is chosen. In Destination, provide a name for the copy of the database. Keep the Tfs_ prefix, and add a distinct name. Typically, that name is the name of the split project collection. In Restore plan, make sure that the backup sets to restore are the ones you want to restore to. To make sure that these are valid sets, select Verify Backup Media and then, in Select a page, select Options.
In Restore options, leave all the check boxes blank. Make sure that Recovery state is set to RESTORE WITH RECOVERY. In Tail-Log Backup, clear the Leave source database in the restoring state check box, and then select OK.

Tip

If the restore operation fails with an error message indicating that the database is in use and cannot be overwritten, you may need to manually configure all the logical file names to reflect the new name for the database. In Select a page, select Files, select the ellipsis button next to each file being restored, and make sure that the names of the files reflect the new name for the database, not the old one. Then try the restore operation again.

2-b. Attach the original collection database

After you have restored the database with a different name, reattach the original collection database to the deployment of Azure DevOps Server.

Attach the collection

Open the administration console for Azure DevOps.
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.
On the Enter the project collection information page, provide a name for the collection in Name if one is not already present. Since this is the original collection, you can select to leave the name the same as it was before. In Description, optionally provide a description of the collection.
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, and close the wizard.
The project collection appears in the list of collections in the administration console. If the collection state is listed as Online, you must stop it before continuing. Select the collection from the list, and on the General tab, select Stop Collection.

2-c. Attach the renamed collection database

After you attach the original collection database, you must attach the renamed collection to the deployment of Azure DevOps Server. When this collection is attached, it will remain stopped. You will not be able to start it until all duplicate projects have been removed.

Attach the renamed collection database

Open the administration console for Azure DevOps.
Select Project Collections, and then select Attach Collection to open the wizard.
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 renamed collection database, if it is not already listed.
In the Databases list, select the renamed collection database.
On the Enter the project collection information page, enter a name for the renamed collection in Name that differs from the name of the original name of the collection. This should match the name you gave the renamed database, without the Tfs_ prefix.
(Optional) In Description, enter a description of the collection.
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, and then close the wizard.
The name of the collection appears in the list of collections in the administration console, and its status should display as Offline.
To ensure that both collections have attached with unique IDs, in the administration console, go to Event Logs and open the log files for both collection attach operations. The GUIDs for CollectionProperties should not match.

In the unlikely event that the CollectionProperties GUIDs do match, change the ID to a unique ID before continuing by running the TFSConfig Collection command on the second collection with the /clone parameter.

2-d. Delete projects on the split collections

Now that you have two copies of the collection attached to Azure DevOps Server, you must delete each project from either the original collection or the renamed collection so that no project remains in both collections.

Important

A project cannot exist in more than one collection. Until you delete all duplicated projects between the split collections, you will not be able to start the renamed collection.

Delete projects from the collections

Open the administration console for Azure DevOps.
Select Project Collections, and in the list of collections, select the original project collection that you stopped in order to split it.
On the Projects tab, in the list of projects, select a project to delete from the collection, and then select Delete.

Tip

You can select more than one project to delete at a time.
Select the Delete workspace data check box, leave the Delete external artifacts check box cleared, and then select Delete.

If the Delete external artifacts check box is not cleared and your project is configured to use Lab Management, the virtual machines and templates that are associated with the project will be deleted from System Center Virtual Machine Manager. They will no longer be available to the project in the renamed collection. (Note that Lab Management has been deprecated for TFS 2017 and later versions.)
When you have finished deleting the projects you do not want hosted in the original project collection, select the renamed project collection from the list of collections. Then, on the Projects tab, delete the unwanted projects from the new collection.
Repeat the steps in this section until both collections contain a set of unique projects.

2-e. Start the project collections

After you delete projects, restart both collections.

Start a project collection

Open the administration console for Azure DevOps.
Select Project Collections, and in the list of collections, select the collection that you stopped in order to split it.
On the General tab, select Start Collection.
Repeat step 2 for the collection that you attached with a new name.

3-a. Configure users and groups for the split collections

You can skip this procedure if both split collections will remain in the same domain and you want to allow access for the administrators of the original collection to both collections.

After you have split a collection, you must update the permission groups for both collections with users and groups that will administer those collections. For more information, see Set administrator permissions for project collections.

3-b. Configure users and groups for projects

You can skip this procedure if the split collections will remain in the same domain and you want to allow access for the users of projects in the original collection to both collections.

After you configure administrators for both collections, either you or those administrators must configure access for users and groups to the projects in each collection. Depending on your deployment, you may also need to configure permissions for those users in Reporting Services. For more information, see Add users to projects or teams.

Q & A

Q: My deployment uses reporting. Are there any additional steps I need to take when splitting collections?

A: Yes, you'll need to split reports after you've finished deleting projects so that both collections have a unique set of projects. You'll also need to rebuild your data warehouse.

After you delete projects, move the reports that the split collection uses into a different folder, and then delete them from the original folder.