Upgrade your deployment to the latest version of Azure DevOps Server

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

This article provides general information for upgrading an on-premise deployment to TFS 2018, Azure DevOps Server 2019, or Azure DevOps Server 2020. The general upgrade process is as follows:

  • Prepare your environment. New system requirements might require an upgrade to hardware or software. Either way, an upgrade is a good time to consider whether the current environment meets your needs, or if it makes sense to make changes.

  • Expect the best, prepare for the worst. Even though Azure DevOps Server upgrades are reliable, it always makes sense to prepare for a worst-case scenario. Make sure you have a complete and consistent set of database backups available.

    Note

    If you upgrade in place and don't move to new hardware, consider a dry run of your upgrade in a pre-production environment.

  • Do the upgrade. After you finish your preparation, install the new version. Get the binaries and run through the installation process to upgrade your servers.

    Tip

    In some circumstances you may need to uninstall the previous version of Azure DevOps Server and install the latest version of the Azure DevOps Server for the same machine. In these cases, the installer will display a warning and you should follow the instructions in the warning message.

  • Configure new features. You might need to configure each project to gain access to new features that were made available. You don't have to make all configurations immediately, but some features aren't available until they're configured. Based on your project, use the Configure Features wizard to make changes or make changes manually by updating XML definition files.

Supported upgrade paths

For previous versions of Azure DevOps on-premises servers, the following upgrade matrix shows the proper steps to upgrade based on the version you upgrade from. (Make sure you select the content version that matches the server version you want to upgrade to.)

TFS 2018 Upgrade path matrix for all previous versions.

Before you upgrade to Azure DevOps Server 2020

When upgrading your on-premises deployment to Azure DevOps Server 2020 you should be aware that upgrade from TFS 2015 and later versions are only supported. If you are using TFS 2013 or earlier versions, you need to upgrade to TFS 2015 first.

Before you upgrade to Azure DevOps Server 2019

When upgrading your on-premises deployment to Azure DevOps Server 2019 you should be aware of the following two items that impact work tracking customization and reporting.

Availability of Inheritance process model for new project collections

Azure DevOps Server 2019 provides support for using the Inheritance process model to customize your work tracking experience. You can only get access to this feature by creating a new project collection. Existing project collections will only support the On-premises XML process model.

If you choose the Inheritance process model for new project collections, you also automatically choose the Analytics Service to support reporting. You won't be able to add SQL Server reporting services to projects you add on the new project collections. If you choose On-premises XML process model for new project collections, you have access to both the Analytics Service and SQL Server reporting services. This is also true for existing collections that you upgrade.

So, you'll want to consider your work tracking customization and reporting requirements as you move forward with new project collections. To learn more about these choices, see the following articles:

Deprecation of the Configure Features wizard

In the past, the Configure Features wizard was used to update default process templates with updates made to them. This feature is no longer supported in Azure DevOps Server 2019.

To learn about updates made to default system processes, see Changes made to process templates.

Before you upgrade to TFS 2018

Since TFS 2017.2, the old work item form <Layout> tag was deprecated and is no longer supported. If you upgrade your server and have a collection where the new work item form isn't enabled, you might see the following warning during validation:

[VS403364]: This release introduces major updates to the work item form layout and functionality and deprecates legacy custom controls. Consequently, the upgrade process will update all work item type definitions to use the new work item form WebLayout element and remove all custom controls. For more information and recommended upgrade steps, see the Deployment Guide.

For more information, see Handle a TFS 2018 upgrade from the old form to the new form.

Complexity

Upgrading an Azure DevOps on-premises deployment can differ based on the specifics of your existing deployment. Factors that influence the complexity and duration of your upgrade include the:

  • Number of servers deployed
  • Deployment configuration and integration with SQL Server Reporting Services
  • Size of the databases
  • Version of the upgrade.

In all cases, the general process is logically the same. Make sure your environment is ready. Then prepare and do the upgrade.

Downtime

Your Azure DevOps on-premises deployment is offline for the duration of the upgrade. Upgrade times can differ based on the size of the deployment. To keep your upgrades comparably fast, clean up unnecessary data. It also helps if you keep up with the latest versions of Azure DevOps Server.