Unless specifically noted, TeamCity does not support downgrade between major/minor releases (changes in first two numbers of the version). It is strongly recommended to back up your data before any upgrade. |
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.
On this page:
Before upgrading TeamCity:
To upgrade the server:
If you plan to upgrade a production TeamCity installation, it is recommended to install a test server and check its functioning in your environment before upgrading the main one.
Before upgrading, please make sure the maintenance period of your licenses is not yet elapsed (use Administration | Licenses TeamCity server web UI page to list 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 releases list.
Typically all the bugfix updates (indicated by changes in the Z part of the X.Y.Z TeamCity version) use the same effective release date (that of the major/minor 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 an evaluation license on the download page. Please note that each TeamCity version can be evaluated only once. To extend the evaluation 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.
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 major.minor version and are possible within bugfix releases (without changing major.minor version).
The general policy is that bugfix updates (indicated by changes in the Z part of the X.Y.Z TeamCity version) do not change data format, so you can freely upgrade/downgrade within the bugfix versions. However, when upgrading to the next major or minor version (changed X or Y in X.Y.Z TeamCity version), you will not be able to downgrade with the data preservation: you will need to restore a backup of the appropriate version.
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 (e.g. 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.
Important note on TeamCity data structure upgrade
|
If you accidentally performed an inconsistent upgrade, check the recovery instructions.
Used in UI |
Since TeamCity 2017.2 automatic update option is available.
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 upgrade if you want to use that instead of performing the manual updating procedure.
The automatic update procedure is as follows:
In case of an automatic update failure, perform the following to restore your TeamCity to the state prior to the update:
|
Current automatic update limitations:
<TeamCity home>\jre
directory.Run the new installer and point it to the same place TeamCity is installed into ( 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.
The main server configuration file |
<TeamCity data directory
>
used by the previous installation.<TeamCity home>\jre
directory previously backed up or repeat the 64 bit Java installation steps.conf\teamcity-server-log4j.xml
file and want to preserve it (note, however, that customizing the file is actually not recommended, use 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.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.
Please note that it is recommended to use .tar.gz
or .exe
TeamCity distribution. Using .war
is not a recommended way to install TeamCity.
<TeamCity Home Directory>
or [TOMCAT_HOME]/webapps/TeamCity/*
if you are installing from a war file). It's advised to backup the directory beforehand.work
directory. Please note that this may affect other web applications deployed into the same web server.If you made no changes to the container, you can just stop the running container, pull the new version of the official TeamCity image and the server in it via the usual command. If you changed the image, you will need to replicate the changes to the new TeamCity server image.
Please see the dedicated page.
Upgrading TeamCity started from AWS CloudFormation template For template versions dated by November 1, 2017 and later: Connect to the file /home/core/update-teamcity.sh on your TeamCity server EC2 instance using SSH and run it as root superuser using the following commands: $ ssh -i <key> core@<server_address> core@ip-x-x-x-x ~ $ sudo /home/core/update-teamcity.sh For template versions prior to November 1, 2017: Run the following copmmand: $ ssh -i <key> core@<server_address> core@ip-x-x-x-x ~ $ sudo bash ip-x-x-x-x core # /usr/bin/docker pull jetbrains/teamcity-server:latest ip-x-x-x-x core # /usr/bin/systemctl restart teamcity-server.service |
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 on user profile.
Generally, versions of the IntelliJ IDEA TeamCity plugin, Eclipse TeamCity plugin, and Visual Studio TeamCity Addin 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.
The only exception is TeamCity versions 9.0 - 9.1.x, which use a compatible protocol, and any plugin of these versions can be used with any server of these versions. Updating IDE plugins to the matching server version is still recommended.
On starting TeamCity server (and updating agent distribution 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.
Since TeamCity 2018.2, 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 web 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.
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 if to
<Agent Home>/conf/buildAgent.properties
file.buildAgent.properties
file to the same location.If you need to preserve all the agent data (e.g. to eliminate clean checkouts after the upgrade), you can:
conf
.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.
Version 2.0 of TeamCity migrated to the new way of managing Windows service (service wrapper) for the build agent: Java Service Wrapper library.
One of the advantages of using the new service wrapper is the ability to change any JVM parameters of the build agent process.
1.x versions installed Windows service under the name of agentd, while 2.x versions use the TeamCity Build Agent Service <build number> name.
The service wrapper will not be migrated to the new version automatically. You do not need to use the new service wrapper unless you need its functionality (like changing the agent's JVM parameters).
To use the new service wrapper, uninstall the old version of the agent (with Control Panel | Add/Remove Programs) and then install a new one.
If you customized the user under which the service is started, do not forget to customize it in the newly installed service.
If the service wrapper needs an update, the new version is downloaded into the <agent>/launcher.latest
folder, however the changes are not applied automatically.
To upgrade the service wrapper manually, do the following:
<agent>/launcher.latest
folder exists.<agent>\bin\service.stop.bat
.service.uninstall.bat
.<agent>/launcher/conf/wrapper.conf
file.<agent>/launcher
.<agent>/launcher.latest
to <agent>/launcher
.<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.<agent>\bin\service.install.bat
.Start the service using <agent>\bin\service.start.bat
.
This procedure is applicable ONLY to an agent running with new service wrapper. Make sure you are not running the agentd service. |
See also:
Concepts: TeamCity Data Directory |