Upgrading TeamCity Server and Agents

TeamCity supports upgrades from any of the previous versions to the later ones. All the settings and data are preserved unless noted in the Upgrade Notes.

It is recommended to plan for regular upgrades to run the latest TeamCity version at least after several bugfix updates are released. This way, you run a fully supported version with the latest fixes and security patches.

Security Patches

TeamCity is a web application that heavily relies on communications among the server, build agents, VCS providers, and other external services (such as AWS S3 buckets or Nexus LFS repositories). As such, when deployed in non-closed environments, TeamCity is vulnerable to attacks exploiting common vulnerabilities and exposures (CVEs), including those inherited from third-party solutions and libraries it employs.

To reduce the risks, it is highly advised to promptly install any updates containing security fixes. Fixes that eliminate non-critical security vulnerabilities are addressed in regular bug-fix updates. Refer to the Release Notes and check out our Security Bulletin for the list of fixed issues.

Critical vulnerabilities that present major security threats are fixed in separate unscheduled security patches. Once a solution is found, these patches are released immediately. If such an update is available, TeamCity automatically downloads it and prompts administrators for installation.

To stop TeamCity from automatically downloading these patches, uncheck the "Automatically download available security patches and notify administrators when they are ready to be installed" option on the Administration | Updates page. However, we strongly advise against disabling this feature, as it guarantees rapid responses to emerging security threats and ensures swift updates.

Before Upgrade

Before upgrading TeamCity:

For a major upgrade, review what you will be getting in What's New.
Check your license keys unless you are upgrading within bugfix releases of the same major YYYY.MM version.
Download the new TeamCity version (see links to all released versions).
Carefully review the Upgrade Notes.
Consider probing the upgrade on a test server.
If you have non-bundled plugins installed, check plugin pages for compatibility with the new version and upgrade/uninstall the plugins if necessary.
Make sure that TeamCity is running under a user account that has read and write permissions for both the installation and TeamCity data directories.

To upgrade the server:

Back up the current TeamCity data including settings, database, and supplementary data. You will need the backup to roll back to the previous version in the unlikely event of the upgrade failure.
Perform the upgrade steps:
- Upgrading Using Windows Installer
- Manual Upgrading on Linux

Licensing

Before upgrading, make sure the maintenance period of your licenses is not yet elapsed (use the Administration | Licenses page to see your license keys). The licenses are valid only for the versions of TeamCity with the effective release date within the maintenance period. Check the effective release date on the release list.
Typically all the minor updates (indicated by changes in the B part of the YYYY.MM.B TeamCity version) use the same effective release date (that of the major release).
If not all the licenses cover the target version release date, consider renewing the licenses before the upgrade (you can replace the old license keys with the renewed ones even before the upgrade).

If you are only evaluating a newer version, you can get a trial license on the download page. Note that each TeamCity version can be evaluated only once. To extend the trial period, contact the JetBrains sales department.

When upgrading from TeamCity 4.x or earlier, note that the licensing policy in TeamCity versions 5.0 and later are different from that of the previous TeamCity versions. Review the Licensing Policy page and the Licensing and Upgrade section on the official site.

Upgrading TeamCity Server

TeamCity supports upgrades from any of the previous versions to the current one.
Unless specifically noted, downgrades with preserving the data are not possible with changing the major version and are possible within bugfix releases.

The general policy is that bugfix updates (indicated by changes in the B part of the YYYY.MM.B TeamCity version) do not change data format, so you can freely upgrade/downgrade within the bugfix versions. However, when upgrading to the next major version (changed YYYY.N), you will not be able to downgrade with the data preservation: you will need to restore a backup of the appropriate version. Read more about the release numbering.

On upgrade, all the TeamCity configuration settings and other data are preserved unless noted in Upgrade Notes. If you have customized TeamCity installation (like Tomcat server settings change), you will need to repeat the customization after the upgrade.

The general approach to upgrade is to remove all the files of the previous installation in the TeamCity Server Home and place the new files into the same location. Make sure to preserve the TeamCity Data Directory and the database intact (making a backup beforehand), backing up and restoring previously customized settings (for example, in ...\conf\server.xml, ...\conf\web.xml files) is also necessary. The logs directory (...\logs) can be left with the old installation files.

Agents connected to the server are upgraded automatically.

There are several important issues with data format upgrade:

Data structure downgrade is not possible. Once newer TeamCity version changes the data format of database and Data Directory, you cannot use this data to run an older TeamCity version. Please ensure you backup the data before upgrading TeamCity.
Both the database and the Data Directory should be upgraded simultaneously. Ensure that during the first start of the newer server it uses the correct TeamCity Data Directory that in its turn has the correct database configured in the <TeamCity Data Directory>\config\database.properties file. Also make sure the Data Directory is complete (for example, all the build logs and artifacts are in place), no Data Directory content supports copying from the Data Directory of the older server versions.

If you accidentally performed an inconsistent upgrade, check the recovery instructions.

Automatic Update

To be able to update automatically, the TeamCity server should be able to contact jetbrains.com, download.jetbrains.com and download-cdn.jetbrains.com.

When a new version of TeamCity is detected, the server displays the corresponding health item for system administrators. The item points to the server's Administration | Updates page, where all the versions available for the update are listed. The page contains notes about licenses compatibility, the new version description, and controls to perform the automatic update if you want to use that instead of performing the manual updating procedure.

The automatic update procedure is as follows:

The TeamCity server is stopped.
The update script is run to do the following:
1. Create a backup of the current installation in the <TeamCity Home Directory>/.old directory.
2. Update the stopped server to the new version.
Next, the updated server starts.

The update progress is logged to the <TeamCity Home Directory>/logs/teamcity-update.log file.

In case of an automatic update failure, perform the following to restore your TeamCity to the state prior to the update:

Stop your TeamCity server if it is running.
For each folder that exists in the <TeamCity Home Directory>/.old directory, remove the corresponding folder in the <TeamCity Home Directory>. Do not remove the "bin" folder as some of its files are not backed up to the TC_home/.old directory.
Copy everything from the <TeamCity Home Directory>/.old folder and paste it to <TeamCity Home Directory>, replacing all duplicate files.
Start the TeamCity server.

Other limitations of the automatic update:

Some files like TeamCityService.exe and teamcity-server.bat are not included into the scope of the autoupdate.
Some customizations, for example, installations with changed server context, are not supported by automatic update.
The Windows uninstaller is not updated during the upgrade, so after several updates, old TeamCity version will still be noted in Windows lists. During the uninstallation, not all the TeamCity installation files might be deleted.

Manual Update

Using Windows Installer

Create a backup. You can create a backup with the "basic" profile on the TeamCity Maintenance Mode page on the updated TeamCity start.
Note the username used to run the TeamCity server. You will need it during the new version installation.
If you have any of the Windows service settings customized, store them to repeat the customizations later.
If you are using 64-bit Java to run the service (for example, check for "64" in "Java VM info" on the server's Administration | Diagnostics or in a thread dump), consider backing up the <TeamCity Home Directory>\jre directory.
(optional as these will not be overwritten by the upgrade) Back up customizations of the bundled Tomcat server (like port, HTTPS protocol, and so on) or JRE if any.
Check if you a have local agent installed (though it is not recommended to have a local agent), so that you can later select this option in the installer.
Run the new installer and point it to the same place TeamCity is installed to (the location used for installation is remembered automatically). Confirm uninstalling the previous installation. The TeamCity uninstaller ensures proper uninstallation, but you might want to make sure the TeamCity server installation directory does not contain any non-customized files after uninstallation finishes. If there are any, backup/remove them before proceeding with the installation.
If prompted, specify the <TeamCity Data Directory> used by the previous installation.
(optional as these will not be overwritten by the upgrade) Make sure you have the external database driver installed (this applies only if you use an external database).
Check and restore any customizations of Windows services and Tomcat configuration that you need. When upgrading from TeamCity versions 7.1 and earlier, make sure to transfer the server memory setting to the environment variables.
If you were using 64-bit Java to run the server, restore the <TeamCity Home Directory>\jre directory previously backed up or repeat the 64-bit Java installation steps.
If you use a customized Log4j configuration in the conf\teamcity-server-log4j.xml file and want to preserve it (note that it is recommended using logging presets instead), compare and merge conf\teamcity-server-log4j.xml.backup created by the installer from the existing copy with the default file saved with the default name. Compare the conf\teamcity-*-log4j.xml.dist file with the corresponding conf\teamcity-*-log4j.xml file and make sure that.xml file contains all the .dist file defaults. It is recommended to copy the .dist file over to the corresponding .xml file until you really need the changed logging configuration.
Start up the TeamCity server (and agent, if it was installed together with the installer).
Review the TeamCity Maintenance Mode page to make sure there are no problems encountered, and confirm the upgrade by clicking the corresponding button. Only after that all data will be converted to the newer format.

If you encounter errors which cannot be resolved, make sure old TeamCity is not running/does not start on boot, restart the machine, and repeat the installation procedure.

Using .tar.gz Distributions

Create a backup.
Back up files customized since the previous installation (most probably <TOMCAT_HOME>/conf/server.xml)
Remove old installation files (the entire <TeamCity Home Directory>). It's advised to back up the directory beforehand.
Unpack the new archive to the location where TeamCity was previously installed.
If you use a Tomcat server (your own or bundled in .tar.gz TeamCity distribution), it is recommended to delete the content of the work directory. Note that this may affect other web applications deployed into the same web server.
Restore customized settings backed up in step 2 above. If you have the customized <TOMCAT_HOME>/conf/server.xml file, apply your changes into the appropriate sections of the default file.
Make sure the previously configured TeamCity server startup properties (if any) are still actual.
Start up the TeamCity server.
Review the TeamCity Maintenance Mode page to make sure there are no problems encountered, and confirm the upgrade by clicking the corresponding button. Only after that, all the configuration data and database scheme are updated by TeamCity converters.

Using Docker images

Create a backup.
Back up files customized since the previous installation (most probably <TOMCAT_HOME>/conf/server.xml)
If you have built your own Docker image, rebuild your Docker image based on the new version of the TeamCity server base image.
Invoke docker run to start the new container on the target host (either the official TeamCity image or your rebuilt image).
Review the TeamCity Maintenance Mode page to make sure there are no problems encountered, and confirm the upgrade by clicking the corresponding button.

Upgrading Multinode Setups

The Multinode Setup distributes the tasks performed by your TeamCity server between multiple individual nodes, which significantly boosts the system stability and performance. In this setup, each node needs an individual upgrade. See this section for more information: Upgrade/Downgrade.

IDE Plugins

It is recommended for all users to regularly update their IDE plugins to the latest version compatible with the TeamCity server version in use — at least to the version available from the TeamCity server's Tools section in the user profile.
Generally, the versions of the IntelliJ IDEA TeamCity plugin and Visual Studio TeamCity add-in have to be the same as the TeamCity server version. Users with non-matching plugin versions get a message on an attempt to log in to the TeamCity server with a non-matching version.

Server Rollback

In a rare scenario of an automatic or manual server upgrade failing, you can restore TeamCity to its previous state. See the following articles for more information:

Upgrading Build Agents

Automatic Build Agent Upgrading
Upgrading Build Agents Manually
- Upgrading the Build Agent Windows Service Wrapper

Automatic Build Agents Update

On starting the TeamCity server (and updating agent distributions or plugins on the server), TeamCity agents connected to the server and correctly installed are automatically updated to the version corresponding to the server. This occurs for both server upgrades and downgrades. If there is a running build on the agent, the build finishes. No new builds are started on the agent unless the agent is up to date with the server.

Before starting the agent upgrade, the agent is checked for free disk space, 3 GB by default. To modify the value required for the upgrade, configure the teamcity.agent.upgrade.ensure.free.space agent property.

The agent update procedure is as follows: The agent (agent.bat, agent.sh, or agent service) will download the current agent package from the TeamCity server. When the download is complete and the agent is idle, it will start the upgrade process (the agent is stopped, the agent files are updated, and the agent is restarted). This process may take several minutes depending on the agent hardware and network bandwidth. Do not interrupt the upgrade process, as doing so may cause the upgrade to fail and you will need to manually reinstall the agent.

If you see that an agent is identified as "Agent disconnected (Will upgrade)" in the TeamCity UI, do not close the agent console or restart the agent process, but wait for several minutes.

Various console windows can open and close during the agent upgrade. Please be patient and do not interrupt the process until the agent upgrade is finished.

Manual Build Agents Update

All connected agents upgrade automatically, provided they are correctly installed, so manual upgrade is not necessary.

If you need to upgrade agent manually, you can follow the steps below.

As TeamCity agent does not hold any unique information, the easiest way to upgrade an agent is to:

Back up the <Agent Home>/conf/buildAgent.properties file.
Uninstall/delete existing agent.
Install the new agent version.
Restore the previously saved buildAgent.properties file to the same location.
Start the agent.

If you need to preserve all the agent data (for example, to eliminate clean checkouts after the upgrade), you can:

Stop the agent.
Delete all the directories in the agent installation present in the agent .zip distribution except conf.
Unpack the .zip distribution to the agent installation directory, skipping the "conf" directory.
Start the agent.

In the latter case, if you run the agent under Windows using a service, you may also need to upgrade the Windows service as described below.

Upgrading the Build Agent Windows Service Wrapper

If the service wrapper needs an update, the new version is downloaded into the <agent>/launcher.latest directory, however the changes are not applied automatically.

To upgrade the service wrapper manually, do the following:

Ensure the <agent>/launcher.latest folder exists.
Stop the service using <agent>\bin\service.stop.bat.
Uninstall the service using service.uninstall.bat.
Backup the <agent>/launcher/conf/wrapper.conf file.
Delete <agent>/launcher.
Rename <agent>/launcher.latest to <agent>/launcher.
Edit the <agent>/launcher/conf/wrapper.conf file. Check that the wrapper.java.command property points to the java.exe file. Leave it blank to use the registry to look up java. Leave java.exe to look up java.exe in PATH. For a standalone agent, the service value should be ../jre/bin/java, for an agent installation on the server the value should be ../../jre/bin/java. The backup version of the wrapper.conf file can be used.
Install the service using <agent>\bin\service.install.bat.
Make sure the service is running under the proper user account. Please note that using SYSTEM can result in failing builds which use MSBuild/Sln2005 configurations.
Start the service using <agent>\bin\service.start.bat.

Last modified: 04 December 2024