Share via

Move from one environment to another for Azure DevOps on-premises

  • 06/06/2025

Azure DevOps Server 2022 | Azure DevOps Server 2020 | Azure DevOps Server 2019

This article explains how to move an Azure DevOps Server deployment from one environment to another, such as changing the domain name or moving from a workgroup to a domain. Environment-based moves are common when organizations restructure their IT infrastructure, update domain names, or consolidate resources.

You can find step-by-step guidance for preparing your deployment, updating permissions and accounts, stopping services, backing up data, joining the new domain, migrating user and service accounts, configuring reporting and analysis services, updating backup plans, and restarting services.

Changing the environment for Azure DevOps Server requires careful planning, especially around account and identity management, to avoid conflicts and ensure a smooth transition. This article provides best practices and detailed instructions to help you successfully complete the move.

Important

In some situations, you might want to change the domain of an Azure DevOps Server deployment and its hardware. Changing the hardware is a restoration-based move, and you should never combine the two move types. First complete the hardware move, and then change the environment.

Changing identities in Azure DevOps Server as part of an environmental move is the aspect that most often causes conflicts or problems. The Identities Command is a powerful tool, but it has certain limitations. Read up about it as part of planning your move. To help ensure a successful move, make sure that you understand the following requirements:

  • Once a user account is present in Azure DevOps Server, it can't be removed or have another account mapped to it. For example, if you're moving DomainA/UserA to DomainB/UserB, the Identities command would only work to migrate the user if DomainB/UserB isn't already present in Azure DevOps Server.
  • Because the members of the local Administrators group are automatically added to Azure DevOps Server, make sure to remove any accounts that you want migrated from that group before you change the domain or environment.

For further background information, see this blog post.

1. Check permissions and accounts

To change the environment for Azure DevOps Server, sign in as an administrator on the local computer, Azure DevOps Server, SQL Server, reporting, and any other dependent software (such as Project Server). Avoid using accounts you plan to migrate—members of the local Administrators group are automatically added to Azure DevOps Server, which can cause migration issues. Use a dedicated administrative account for the move to prevent conflicts.

Verify administrator-level permissions

  • Ensure the account you're using is a member of the following groups:
    • Servers: Administrators (local Administrators group or equivalent)
    • Azure DevOps Server: Team Foundation Administrators and Admin Console Users
    • SQL Server: sysadmin

If you aren't a member of one or more of these groups, get permissions now.

After confirming your account has all necessary permissions, check for potential conflicts with account or group names in the target environment. Since accounts in the local Administrators group can't be migrated, remove any accounts you plan to migrate from that group before proceeding.

Remove accounts to be migrated from local Administrators group

Open the local Administrators group and remove any accounts you plan to migrate to the new environment. Repeat this process for any other groups that could be affected.

Next, review the list of identities in your current Azure DevOps Server environment. Identify any potential conflicts with groups or user accounts that may already exist in the new environment.

Tip

Create a table or migration map of identities to be moved. Include details about accounts that can't be migrated automatically to help track and resolve issues during the move.

Check identities

  1. On the application-tier server for Azure DevOps, open a Command Prompt window with administrative permissions, navigate to %ProgramFiles%\Microsoft Visual Studio 12.0 Team Foundation Server\Tools, and run the following command to view the identities currently in the system:

    TFSConfig Identities

A list of identities displays.

  1. Review users and groups to identify any duplicate or conflicting identities in the target environment before moving Azure DevOps Server. Resolve any potential conflicts to ensure a smooth migration.

2. Stop services

Stopping the services prevents users from making changes to work items or checking in source code to the original deployment during or after the move process.

  1. Open a Command Prompt window on the application-tier computer and change directories to Drive:\\%programfiles%\\TFS 12.0\\Tools.

  2. Enter the following TFSServiceControl command:

    TFSServiceControl quiesce

3. Back up the databases and the SQL Server Reporting Services encryption key

  1. Open the administration console for Azure DevOps Server and go to the Scheduled Backups page. Take a full backup to immediately back up everything specified in your backup plan. If your deployment uses reporting, include the encryption key in this backup set.

    You can close the window while the job completes

    Note

    If you never configured backups, create a backup plan before taking a full backup.

  2. After the backup completes, confirm that the backup is available on your storage device or network share, and verify you can access it from the new hardware.

4. Join the application tier server to its new domain

  1. On each server, open the computer properties.

  2. Change the computer's settings to join the desired domain or workgroup.

    If prompted, enter the credentials of an account with permission to join the computer to the domain.

  3. Restart the computer to apply the domain change.

    Note

    After restarting, you might see a warning that some services or drivers couldn't be started. You can safely continue with the next procedure.

5. Move user accounts and service accounts

Migrating accounts is often the most challenging part of changing environments, especially if you didn't plan your user migration carefully. The TFSConfig Identities command cannot migrate an account to a target account that already exists in Azure DevOps Server.

If the account names are identical in both domains (with only the domain name differing), you can use the batch mode of TFSConfig Identities to update all identities at once. If account names differ between environments, you must update each identity individually and specify the new target account name, as described below.

  1. On the application-tier server for Azure DevOps, open a Command Prompt window with administrative permissions. Navigate to %ProgramFiles%\Microsoft Visual Studio 12.0 Team Foundation Server\Tools, and run the following command to update the service account's SID to the new domain:

    TFSConfig identities /change /fromdomain:OldComputerorDomainName /todomain:NewDomainName /account:OldTFSServiceAccount /toaccount:NewTFSServiceAccount

    Warning

    If your service account was a system account (such as Network Service), you can't migrate it directly because a system account with the same name exists in the new environment. You need to follow a two-stage process. See the example in Identities Command.

  2. To migrate all accounts with the same name in the new environment, run:

    TFSConfig Identities /change /fromdomain:OldDomainName /todomain:NewDomainName

    This command batch processes the accounts.

  3. If your new domain contains identities with different names between environments, manually update the SIDs for each. For example, if Christie Church's account was Fabrikam\CChurch in the old environment and is NewFabrikam\ChristieC in the new one, update their SID as follows:

    TFSConfig Identities /change /fromdomain:OldDomainName /todomain:NewDomainName /account:OldAccountName /toaccount:NewAccountName

  4. Update the service account by running:

    TFSConfig Accounts /change /AccountType:ApplicationTier /account:AccountName /password:Password

  5. If your deployment uses reporting, update the data source account:

    TFSConfig Accounts /change /AccountType:ReportingDataSource /account:AccountName /password:Password

  6. If your deployment uses Azure DevOps Proxy Server, update the proxy service account:

    TFSConfig Accounts /change /AccountType:Proxy /account:AccountName /password:Password

    Note

    If you're moving to a non-trusted domain, you might also need to manually add users and groups to teams, projects, collections, and Azure DevOps Server itself. For more information, see Add users to projects, Set administrator permissions for project collections, and Set administrator permissions for Azure DevOps Server.

  7. If your deployment integrates with Project Server, you might need to perform other steps to configure service accounts with the required permissions. For more information, see Assign permissions to support TFS-Project Server integration and Configure TFS-Project Server integration.

6. Configure Reporting and Analysis Services

Skip this procedure if your deployment does not use reporting.

If you renamed the report server during the move, update Azure DevOps Server to point to the new report server location. You also need to restart the warehouse and manually rebuild the Analysis Services database.

  1. Open the administration console for Azure DevOps, go to the Reporting node, and edit the settings.

    Reports still point to the old server

  2. Update the values on all three tabs to reflect the new server name. Ensure you enter the correct data source account information for the new environment.

    Make sure the information is correct on all 3 tabs

  3. Select Start Jobs to restart reporting.

  4. Select Start Rebuild to rebuild the warehouse.

7. Configure backups

If you changed the network share name or storage device during the domain name change, update your scheduled backup plan to reference the new resources.

In the administration console, go to the Scheduled Backups node and reconfigure the scheduled backups to back up the Azure DevOps Server databases on the new server. For details, see Create a backup schedule and plan.

8. Restart services

Now that you updated Azure DevOps Server with all the information for the new environment, to restart the services, do the following steps:

  1. On the Azure DevOps Server application-tier computer, open a Command Prompt window with administrative permissions and change directories to Drive:\%programfiles%\TFS 12.0\Tools.

  2. Enter the following TFSServiceControl command:

    TFSServiceControl unquiesce

FAQs (frequently asked questions)

Q: I want to change the physical server or servers for my deployment, not domains. Can I do that?

A: Yes, this action is called a hardware-based move, and the steps are provided in Move or clone from one hardware to another. You shouldn't try to combine an environment-based move with a hardware-based move. First complete the hardware move, and then change the environment.