- For a major upgrade, review what you will be getting in What's New (follow the links at the bottom of What's New if you are upgrading not from the previous major release)
- Check your license keys unless you are upgrading within bugfix releases of the same major X.X version
- Download the new TeamCity version (extended download options)
- 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
- Back up the current TeamCity data
- Perform the upgrade steps:
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.
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. For that to function, TeamCity server should be able to contact https://www.jetbrains.com site.
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.
- some customizations, e.g. installations with changed server context, are not supported by automatic update
- only manual upgrade is possible if the server is deployed from a .war distribution, or runs under the official TeamCity Docker container, started with AWS CloudFormation template or Azure Azure Resource Manager template.
- 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 of the TeamCity installation files might be deleted.
- the bundled Java is not updated
- with several nodes installation, only the main TeamCity server can be auto-updated, the Running Builds node needs to be updated manually.
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.
Upgrading Build Agents
- Automatic Build Agent Upgrading
- Upgrading Build Agents Manually
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.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.
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.