Upgrade Notes

• Requests sent by the GitHub Commit Hook plugin fail with the "403: Access Denied" error. Update your plugin to version 2022.04-109057 to resolve this issue. See this YouTrack ticket for more information: TW-86680.

• The Administration page is not accessible from TeamCity UI if the plain-text LDAP connection URL (ldap://...) is used. To resolve this issue, switch to a secure LDAPS connection (recommended) or add an internal property as suggested in the following ticket: TW-88069.

• There is a new performance problem in the Git plugin which slows down checking for changes operation for some of the Git repositories. For the issue to reproduce, a VCS root should have "Enable to use tags in the branch specification" option enabled and +:refs/tags/* should be specified in the VCS root branch specification. The repository should also have many thousands of tags. Please see TW-76397 for a workaround.

Some popular external plugins are not compatible with TeamCity 2022.04 and have to be updated before the upgrade.

Download newer versions of these plugins from JetBrains Marketplace:

• Github Commit Hooks

• Hashicorp Vault Support

• Gradle Build Scan

• Versions 2017.1 and 2017.2 of TeamCity REST API have been unbundled. If you have been using any of these versions in your scripts, consider switching to the latest protocol version as described here. If switching is not an option and this is a breaking change for your setup, please contact us via any convenient feedback channel.

• Updates in TeamCity Agent Docker images:

  • The bundled .NET Core SDK has been updated to 6.0.100.

  • The two bundled versions of .NET Core Runtime are 3.1.21 and 5.0.12.

  • Bundled Git has been updated to version 2.36.0

  • The bundled Java was updated to version 11.0.15.9.1

• Bundled IntelliJ IDEA has been updated to version 2021.2.3. Note that this version requires Java 11.x. Previously added IntelliJ Inspections/Duplicates steps with the bundled version will become incompatible with the agents running Java below version 11.

• The bundled Kotlin compiler used in TeamCity DSL has been updated to version 1.6.21

• The SBT launcher, used in the Simple Build Tool (Scala) plugin, has been updated to version 1.5.5.

• Freemarker, used by TeamCity notification templates, has been updated to version 2.3.31.

• The Qodana plugin has been bundled with TeamCity. If you previously installed the Qodana plugin and used DSL, you'll need to update your DSL settings. We're providing a special version of the plugin that contains both old and new Kotlin DSL settings. All deprecated settings are marked and alternatives are provided. After the migration, you can delete this plugin and use the version bundled with TeamCity.

• The CVS plugin has been unbundled from TeamCity. If you want to continue using it on your server, please download it from JetBrains Marketplace and install it as described here.

• The Eclipse plugin has been unbundled from TeamCity. Contact our support if you need the plugin.

• After upgrading to 2021.2.3, builds might fail to check out sources from git repositories on Azure DevOps (both Server and Services) via SSH. See the related issue for details.
  If you face this problem, please apply a workaround from the issue.

• Builds might fail to publish artifacts or a build number via commands of an MSBuild script. This problem can be worked around by changing the build log verbosity level to normal: to do this, set the msbuild.logger.params configuration parameter to verbosity=normal. Alternatively, you can download the fixed .NET plugin here and install it manually on your server.

• Updates in TeamCity Agent Docker images:

  • The bundled version of .NET Core SDK has been updated to 6.0.100.

  • Bundled two versions of .NET Core Runtime: 3.1.21 and 5.0.12.

• The Perforce Helix Core client (p4) is updated to version 2021.2/2201121.

TeamCity 2021.2 does not introduce any new data formats compared to version 2021.1 and does not contain data converters. This simplifies and thus speeds up the upgrade/downgrade between these versions.

• Can't use remote run from ReSharper and Eclipse with enabled 2FA
  Users who have configured two-factor authentication for their TeamCity accounts, temporarily cannot run and debug TeamCity builds remotely from ReSharper and Eclipse. If using the remote run from these tools is crucial to your pipelines, make sure 2FA is set to Optional on your servers (default option), so users can disable it for their own accounts anytime.

• .NET builds may fail due to enabled deterministic source paths
  Builds with .NET steps may fail with the "SourceRoot items must include at least one top-level (not nested) item when DeterministicSourcePaths is true" error. This error is caused by the conflict between the expected paths' format (deterministic) and the approach used in your project (likely, absolute paths to sources).
  As a workaround, consider adding the /p:ContinuousIntegrationBuild=false command-line argument to disable deterministic source paths, or download and install the fixed .NET runner as described here.

• .NET builds fail if .NET version is < 6.0 and a path to a build agent contains whitespaces
  If you run a build with a .NET step on a build agent that has whitespaces in its OS path and the used .NET version is earlier than 6.0, the build will fail with the "Only one project can be specified" error.
  As a workaround, consider switching to .NET 6.0, or download and install the fixed .NET runner as described here.

• Invalid property errors when passing .NET parameters containing special characters
  If running .NET commands via the .NET runner results in the "Property is not valid" error, you may need to adjust the system parameters being passed to it. Since version 2021.2, the .NET runner no longer escapes special characters in parameters. This new approach allows passing lists of parameters, but might cause errors if your existing parameters contain such special characters.
  To resolve this issue, please revise and adjust the parameters being passed — make sure to escape all the occurring special characters in them.

• Microsoft Azure agents fail to automatically start/stop
  Build agents running in the Microsoft Azure cloud may fail to automatically start/stop and, after a timeout, freeze in the "Scheduled to Stop" state.
  To work around this issue in the Azure plugin, please set the teamcity.kotlinCoroutinesPool.configurator.enabled=false internal property. This issue will be automatically resolved on upgrading to the next bugfix update.

• Builds using Ruby Environment Configurator have no compatible agents
  Enabling the Ruby Environment Configurator feature in a build configuration will add the env.AAAA agent requirement to it. Thus, the build agents that don't have this environment variable will be marked as incompatible, and TeamCity won't be able to run this build on them.
  To work around this issue, please update the Ruby plugin to the fixed version as described here. This issue will be automatically resolved on upgrading to the next bugfix update.

• DSA/DSS SSH keys can't be used in TeamCity 2021.1.4 and 2021.2
  After upgrading to any of these versions, the SSH keys of the DSA/DSS format are rejected with the "ssh-dss cannot be used as public key type for identity" error.
  To continue using them in TeamCity, please follow this workaround.

• UnknownHostException when fetching files from Git LFS 3.0.0
  Users might get the java.net.UnknownHostException error when fetching files to build agents from Git LFS 3.0.0. This version switched to the pure SSH protocol. According to this protocol, it adds — before the host name. The JSch library used by TeamCity for SSH connections doesn't support them and treats these symbols as a part of the host name.
  To work around this issue, set the teamcity.git.use.native.ssh=true build configuration parameter. Alternatively, you can temporarily downgrade Git LFS to a version earlier than 3.0.0. This issue will be fixed in TeamCity 2021.2.1.

• C# Script builds may fail if .NET profiling is enabled
  Running a build with C# Script steps on .NET with enabled profiling may result in the "Failed to create CoreCLR, HRESULT: 0x80004005" error. This issue can occur only if .NET is launched inside a Docker container or in Windows Subsystem for Linux (WSL).
  To work around it, add an environment variable COMPlus_EnableDiagnostics=0 to your build configuration.

• TeamCity fails to initialize a cloud client when creating an Amazon EC2 spot fleet profile
  When creating a cloud profile for an Amazon EC2 spot fleet, users might get the "Failed to initialize cloud client 'amazon'. An exception occurred while parsing config." error. This error only occurs if the "Specify instance attributes that match your compute requirements" option is enabled in the current fleet's instance type requirements.
  To work around this issue, please remove the InstanceRequirements block from the fleet's JSON configuration file before uploading it to TeamCity. This issue will be fixed in TeamCity 2022.1.

• Builds might fail to publish artifacts to Amazon S3 if AWS KMS is used
  After updating to 2021.2, builds might start failing on an attempt to publish artifacts to an Amazon S3 bucket encrypted with an AWS KMS key. This issue is caused by the recently added integrity check for build artifacts. To temporarily disable it in a project and workaround the issue, set the teamcity.internal.storage.s3.upload.enableConsistencyCheck=false property on a project level.
  This problem will be fixed in TeamCity 2021.2.3.

The support for the bidirectional agent-server communication protocol has been stopped. Since version 2021.2, agents will connect to the server exclusively via the unidirectional protocol.

To upgrade TeamCity from versions earlier than 9.1, where the unidirectional support was first introduced, to 2021.2, use one of the following methods:

• Upgrade the server to version 2021.1, wait until all the agents upgrade as well, and then upgrade the server to 2021.2.

• Upgrade the server to version 2021.2, uninstall the old agents manually, and then install the new agents.

If you use VCS labeling for a Perforce root, note that TeamCity now creates automatic labels by default. If you want to continue using static labels, you can revert to the previous behavior by adding the teamcity.perforce.useStaticLabels=true internal property.

Previously, builds in an artifact dependency configuration were never cleaned up if its dependent configuration had a snapshot dependency on another build configuration which was set to be preserved. For example, if C artifact-depends on B and snapshot-depends on A and A is set to be preserved, B was not cleaned up even if the "Keep artifact dependencies" option was enabled in C. Now, builds in the artifact dependency configuration (C) will be cleaned up properly, in full accordance with the clean-up rules.

This fix restores the intended behavior, but we recommend that you review your clean-up settings to ensure no builds will be cleaned up unexpectedly after the upgrade.

TeamCity 2021.2 Server supports Java versions 8 and 11, but Java 8 support will be discontinued in TeamCity 2022.04, in April 2022. If you use a non-bundled version of Java 8, we highly recommend that you migrate your server to Java 11 until the 2022.04 release.

Note that TeamCity is not compatible with Java 17, which makes Java 11 the only version planned for support in TeamCity Server 2022.04.

• Bundled Amazon Corretto Java has been updated to version 11.0.12.7.1 in the TeamCity server and agent Docker images for Windows and Linux.

• Bundled Tomcat has been updated to version 8.5.72.

• Bundled JaCoCo has been updated to version 0.8.7.

• Bundled Ant has been updated to version 1.10.11.

• The Bundled Kotlin compiler, used in TeamCity DSL, has been updated to version 1.5.31.

• The bundled dotCover tool has been updated to version 2021.2.2.

• The following notifications plugins are no longer actively used and thus unbundled from TeamCity:

  • Jabber/XMPP

  • RSS feed support
    To proceed using their functionality in TeamCity 2021.2, you need to download the required plugin via the link above and install it as described here.

• Builds that use Git submodules might fail with the "Failed to perform checkout on agent" error. To prevent it, you need to set a branch for each used submodule in .gitmodules.
  This problem will be fixed in version 2021.1.2, but you can already download and install our Git plugin with the fix here.

• If you have added the teamcity.nuget.feed.async.request.enabled internal property to workaround this issue in 2021.1, remember to remove it on upgrading to 2021.1.1.

• VCS roots of archived subprojects are now hidden by default on the Project Settings | VCS Roots page. You can display them by enabling the including archived filter option.

• When trying to load a NuGet package which name contains the . (dot) character, users get the "Could not find acceptable representation" exception in the build log. This is caused by the issue in the new performance optimization algorithm: it truncates the file name to the part preceding the first dot. To workaround this issue, please download the fixed NuGet Support plugin here and upload it in Administration | Plugins. Alternatively, you can temporarily disable the new optimization mode by setting the teamcity.nuget.feed.async.request.enabled internal property to false — note that this property has to be removed after upgrading to TeamCity 2021.1.1.

Git VCS roots now receive the new Checkout Policy option that replaces the Use Mirrors checkbox and provides more flexibility. On upgrading, the roots' settings will keep their selected states. However, Git roots' settings in Kotlin DSL specifications need to be updated.

The useMirrors parameter in the Kotlin DSL of Git VCS roots is deprecated and replaced by the checkoutPolicy parameter that supports the following values: AUTO (default), USE_MIRRORS, NO_MIRRORS, SHALLOW_CLONE.

Non-portable Kotlin DSL format is deprecated. It is no longer possible to create new projects in this format. For compatibility, projects that are already stored in this format will continue working.

The default port in the TeamCity installer for Windows has been changed to 8111. Now, both tar.gz and exe installers use the same port.

TeamCity Lucene-based search now uses the OR operator by default instead of AND. This corresponds to the default Lucene syntax and helps optimize the search behavior and reduce its index size.

The build status icon, available via the default http://<TeamCity Server host>:<port>/app/rest/builds/<buildLocator>/statusIcon REST API endpoint, is now provided in the SVG format instead of PNG. The statusIcon.svg endpoint is still supported for compatibility with existing scripts.
To get a PNG icon, use the statusIcon.png endpoint.

The following old versions of REST API have been unbundled: 6.0, 7.0, 8.1, 9.0, 9.1. If this change causes any problems for your setup, please contact us via any feedback channel.

• Bundled Amazon Corretto Java has been updated to version 11.0.11.9.1 in the TeamCity server Docker images and Windows installers.

• Bundled Ant has been updated to version 1.10.10. Note that this version requires Java 8 or later.

• Bundled dotCover and ReSharper CLT have been updated to version 2021.1.2.

• Bundled JaCoCo has been updated to version 0.8.6.

• The Bundled Kotlin compiler, used in TeamCity DSL, has been updated to version 1.4.32.

• Bundled Kotlin, used in the Kotlin Script build runner, has been updated to version 1.5.0.

• JGit version, used in the Git plugin, has been updated to 5.10.0.202012080955-r.

• SVNKit, used in Subversion VCS roots, has been updated to version 1.10.3.

• The My Settings & Tools page has been renamed to Your Profile.

To ensure that the integration with NuGet is secure, TeamCity now checks if a trusted NuGet installer is used when starting builds on Windows with a NuGet dependency trigger. If your triggers use a NuGet version installed via Administration | Tools, this verification will go smoothly, with no user actions required. Otherwise, you might get the "Problem with NuGet Dependency Trigger" error. The recommended solution is to switch all affected triggers to any NuGet version that has been regularly installed via the TeamCity UI. Such versions automatically appear in the NuGet.exe drop-down menu in the trigger's settings. Alternatively, if you need to use a custom NuGet executable and absolutely trust it, you can add it to the whitelist by specifying the following internal property:

teamcity.nuget.server.cli.path.whitelist=<disk>:\\<path-to-executable>\\NuGet.exe

In this version, we've changed the behavior of SSH authentication with the default private key in the SSH Exec and SSH Upload build runners. Previously, when authenticating via SSH during a build, a build agent would use the username configured in the agent's SSH config or, if it's missing, the name of the OS user who runs this agent. The value of the optional Username field in the build step's settings would always be ignored. Now, if this value is specified, the agent will use it for SSH authentication instead of the one in the SSH config.
If you have previously configured an SSH username directly inside build steps and the Default private key authentication method is selected in these steps, make sure that this username is still relevant and allows for successful authentication.

• In the TeamCity agent Docker image, Docker has been updated to version 19.03.14 and Docker Compose has been updated to version 1.28.5.

• SBT, used in the Simple Build Tool (Scala) plugin, has been updated to version 1.4.7.

IntelliJ IDEA version 2019.2 and earlier, as well as other IntelliJ-based products released prior to IntelliJ platform version 193, is no longer supported by the IntelliJ Platform plugin. See the version compatibility table for details.

• Kotlin, used in TeamCity DSL, has been updated to version 1.4.21.

• The teamcity.tests.recentlyFailedTests.file system property contains the full path to a file with the recently failed tests and can be used to reorder risk tests in custom build runners. Previously, it was always generated by default. Now, it is only provided if the used build runner is set to reorder test runs or if the teamcity.internal.tests.provide.recentlyFailedTests parameter is set to true.

• Windows Docker images of the TeamCity server don't allow restarting the server from the UI. See how to stop and start the server via the command line.

Following the security practices we've applied to our Agent Docker images, the TeamCity Server Docker images for Linux now run under a non-root user by default.

When trying to run a Linux image under a default user, you will get the "Permission denied" error. To prevent it, you need to change the ownership over the host data directories: run chown -R 1000:1000 applied to the required volumes. For large directories, this operation may take a long time and slow down the disk performance.
Alternatively, you can start the container under the root user by passing the -u 0 parameter to the docker run command. This is a quick workaround which allows saving time on changing the directories' ownership. However, we suggest that you stick to the chown approach in the long term.

Since this version, the .NET build runner does not apply -- before the dotnet run parameters. Previously, the runner added this prefix automatically which made it impossible to pass the custom options to the run command. To fix this, we've disabled the previous behavior.
Unfortunately, the affected .NET build steps cannot be converted automatically on upgrading. If any of your steps pass arguments to the running .NET application, please make sure to alter these steps and prepend the respective parameters with --.

• Bundled Tomcat has been updated to version 8.5.61.

• If upgrade fails with an error in OptimizeAndCleanupIdsGroupsTableConverter, please apply the workaround described in this issue.

• TeamCity agent Docker images with the latest tag do not bundle Docker.
  To be able to run Docker in a TeamCity 2020.2 agent, download the teamcity-agent image with the {TEAMCITY_VERSION}-linux-sudo tag instead. More information is available in our Docker Hub documentation.

The new header is enabled in both classic and experimental UIs. Some plugins developed for the previous header might not work in the new one. With our new API, you can make your custom plugins compatible with the new header or write new ones using modern web technologies.

If you have troubles displaying valuable information or actions in this header and updating plugins is not a convenient option, you can set the teamcity.ui.useClassicHeader=true internal property — this will switch your TeamCity header to the previous view. Please note that this is not a recommended solution as we might disable the obsolete header in the future versions.

Lucene version in TeamCity search has been updated to 8.5.1. On upgrading, TeamCity will reindex all builds on the server which might take some time and load the CPU. During reindexing, some builds might not be present in the search results.

The external Python build runner is no longer supported. All existing build steps will continue to work normally, but we recommend switching existing Python steps to the new bundled runner.

• Previously, the Build file field of the Gradle runner was set to build.gradle by default. We have removed this default value as some users rely on custom names of build files and prefer to let Gradle decide what file to choose.
  If build.gradle was selected as a build file in your Gradle steps, this setting will remain. In projects whose settings are stored in VCS, TeamCity will prompt to commit the respective change so the build.gradle property is explicitly specified in the versioned project settings.

• The Gradle runner now displays test names based on the displayName properties assigned to the respective test methods. If your Gradle tests are annotated with a custom displayName property (for example, a JUnit 5 test with the @DisplayName annotation), their names will change in TeamCity on upgrading. This might break test and investigation history in respective builds. To prevent this, consider switching the behavior back with the teamcity.internal.gradle.testNameFormat=name internal property.

Since version 2019.2, a secondary node allows user actions if at least one responsibility is assigned to it. In 2020.2, we have added a new responsibility — "Processing user requests to modify data". Nodes with this responsibility can process all currently supported user actions and allow changing project settings. Without it, a node will provide a read-only interface.
On upgrading, this responsibility will be automatically enabled on all your secondary nodes that have at least one other responsibility. This will ensure no current functionality of these nodes is affected. To allow user actions on new secondary nodes, you have to manually enable the new responsibility in Administration | Server Configuration.

• .NET in TeamCity server and agent Docker images (both Windows and Linux) have been updated to version 3.1.403.

• Java in TeamCity Docker images has been updated:

  • On Windows server images: to Amazon Corretto x64 v.11.0.9.11.2

  • On Linux server images: to Amazon Corretto x64 v.11.0.9.11.

  • On Windows and Linux agent images: to Amazon Corretto x64 v.8.272.10.3

• Java bundled in the TeamCity server and agent Windows installers has been updated to version 11.0.9.11.2.

• Bundled Tomcat has been updated to version 8.5.57.

• The SAC Windows image in the TeamCity server Docker containers has been updated to version 2004. Windows LTS version is 1809, as in TeamCity 2020.1.

• The Linux image in TeamCity server Docker containers has been updated to version 20.04 (LTS).

• Bundled dotCover and ReSharper CLT have been upgraded to version 2020.2.4.

• The deprecated Visual Studio 2003 build runner is disabled in TeamCity. We recommend using the .NET runner instead.
  If you were actively using the VS 2003 runner and cannot easily migrate to the .NET runner, please let us know about it via any of our feedback channels.

• JDBC drivers for external databases, suggested on the fresh TeamCity installation, have been updated to the following versions:

  • MySQL - 8.0.22

  • MSSQL - 8.4.1

  • PostgreSQL - 42.2.18

• When detecting GitHub issues, TeamCity now filters out pull requests that have no issues assigned to them. If you need to display such independent pull requests in the issue log, you can disable this filter by setting the teamcity.issues.github.filter.pull.requests=false internal property.

• Email Notifier now uses the same versions of the TLS protocol as supported by the current TeamCity server's JVM.

• Bundled Amazon Corretto Java has been updated to version 11.0.8 in the TeamCity server installers and Docker images.

• Mercurial, dropped in version 2020.1.2, is again supported in the Windows Server Core agent Docker images.

• If you try to re-run a build that has an artifact dependency but not snapshot dependency on another build, the Re-run build dialog will not load.
  This issue will be fixed in TeamCity 2020.1.4. To workaround it in version 2020.1.3, follow this instruction.

• In the TeamCity classic UI, the Projects link in the header is missing the expand button.
  To workaround this issue, please follow the instruction described here.

• Java 11 has been bundled with the TeamCity server Windows installer and server Docker images instead of Java 8.

• TeamCity agents stop supporting Java versions earlier than 8. If any of your agents run on earlier versions of Java, make sure to upgrade their JRE so you can continue running builds on these agents.

Plugins which implement some build runners might need to be recompiled/upgraded.

The corresponding error might look like java.lang.NoSuchMethodError: jetbrains.buildServer.controllers.admin.projects.BuildRunnerBean.getPropertiesBean when a new build step for the corresponding custom build runner is created or updated.

See the related issues about the Checkmarx plugin and the SonarQube Runner plugin.

To comply with recommended security practices, the TeamCity agent Docker images now run under a non-root user.

This change might affect the following use cases:

• To create/update a custom image based on the standard TeamCity agent image, you might need to switch to the root user first (see the related issue for details).

• If you mount a host directory to a container, you might get the "Permission denied" error. To prevent this issue, try any of the following workarounds:

  • Set the UID of the directories' owner to 1000 with the chown command.

  • Send the --user argument with the docker run command to set the same UID for the Docker user as that of the host machine. For example, use docker run -it --user $(id -u) ....

  • Note that TeamCity automatically creates volumes for writable directories, and there is usually no need to map them explicitly. Consider omitting any explicit references to prevent the permission issues.

TeamCity Windows Tray Notifier has been deprecated in favor of the new Browser Notifier extension.

Windows Tray Notifier will continue working with the new version of TeamCity but we recommend you trying the new extension instead. Note that since version 2020.1, the My Settings & Tools | Notification Rules | Windows Tray Notifier tab in TeamCity has been renamed to Browser Notifier.

The Kubernetes Support plugin is now bundled with TeamCity. On upgrade, it will replace the external plugin if it is installed on your TeamCity server. Note that the bundled plugin does not contain the Helm build runner. To continue using this runner in your build configuration, please install the new external plugin.

TeamCity improves the security of REST API integration mechanisms by introducing CSRF tokens. This change will not affect the behavior of custom integration scripts unless they rely on Cross-Origin Resource Sharing (CORS) in writing operations and the rest.cors.origins internal property is enabled in TeamCity (it is disabled by default).

Previously, CSRF protection was presented in TeamCity with the verification of Origin/Referer headers of HTTP requests. To improve TeamCity CSRF protection, this method has been disabled in favor of a more secure one — CSRF tokens. Since this release, TeamCity stops supporting the CORS mechanism for POST/PUT/DELETE REST API requests. Cross-origin GET requests' headers are processed as before and still require CORS configuration.

If necessary, you can enforce verification of Origin/Referer headers for writing CORS operations by setting the teamcity.csrf.paranoid=false internal property. Note that this is a transitory and less secure solution: we strongly recommend refactoring your existing requests so they comply with the new security policy and provide a token within a CSRF header or parameter. A CSRF token can be obtained via the GET https://your-server/authenticationTest.html?csrf request and provided via the X-TC-CSRF-Token HTTP header to the write CORS requests.

• Bundled IntelliJ IDEA has been updated to version 2020.1.1.

• Bundled Ant has been updated to version 1.9.14.

• Bundled Tomcat has been updated to version 8.5.54.

• Bundled Maven has been updated to version 3.6.3.

• Kotlin, used in TeamCity DSL, has been updated to version 1.3.70.

• JDBC drivers for external databases, suggested on the fresh TeamCity installation, have been updated to the following versions:

  • MySQL - 8.0.20

  • MSSQL - 8.2.2

  • PostgreSQL - 42.2.12

Filtering test occurrences by a branch (.../app/rest/testOccurrences?locator=branch(XXX) request) has been changed. It used to support only branch names with case-sensitive matching. Now, the XXX value supports branch locators (the same as when filtering builds): it is case-insensitive by default and matches the <default> branch display name.

• Now, a user cannot assign a role to another user, if this role has more permissions than the role of the current user.
  If you experience troubles with certain roles being unavailable to users after upgrading to 2020.1, make sure these roles don't comprise any permissions that exceed the rights of the respective project administrators.

• TeamCity has dropped support for Internet Explorer. Please use Microsoft Edge instead.

• Since this version, the new .NET runner, introduced in TeamCity 2019.2.3, is not compatible with the obsolete external .NET CLI Support plugin (used in versions 2017.1 and earlier). If you have previously installed this plugin, please uninstall it from your server to be able to use the new .NET runner.

The .NET CLI (dotnet) build runner has been refactored and renamed to .NET thus emphasizing that now it supports all .NET-related operations previously implemented in TeamCity as multiple build steps.

All existing .NET CLI (dotnet) steps will continue working as usual under the new .NET name, with no additional tuning required.

We stop providing active support for the MSBuild, Visual Studio (sln), Visual Studio 2003, and Visual Studio Tests runners. These steps are left for compatibility of existing build configurations with new versions of TeamCity. We recommend switching all your affected build steps to the .NET runner to receive new features and support in our following versions.

See the .NET description for more information about the new .NET step and migration notes.

note

Since the reworked .NET runner introduces new options and features, you might not be able to use them if downgrading to the earlier versions of TeamCity. In such case, you will have to return to using the obsolete runners after downgrading. To prevent any issues, you can back up your TeamCity data before upgrading to version 2019.2.3.

If you face any problems with migration to the .NET runner or encounter other related issues, do not hesitate to contact us via any convenient feedback channel.

The bundled version of Java in Windows installers of TeamCity Server and Agent as well as in the Docker images is updated to Amazon Corretto 8.252.09.1.

To improve performance on agent checkout, TeamCity caches regular Git repositories on agents. Since this version, it also caches Git submodules.
If your custom scripts or settings depend on the main alternates source for submodules and it causes Git to operate with errors, consider one of the following workarounds:

• Disable the new mirroring mechanism by setting the build parameter teamcity.internal.git.agent.submodules.useMirrors to false.

• Modify your custom settings to point at the parent git directory instead of the exact source directory.

• TeamCity Visual Studio Add-in Web installer has been updated to ReSharper version 2019.3.2.

The bundled version of Java in Windows installers of TeamCity Server and Agent as well as in the Docker images is now 64-bit Amazon Corretto 8 (previous TeamCity versions bundled 32-bit Java, and TeamCity 2019.1 bundled AdoptOpenJDK).

If you were using the default bundled Java on Windows, make sure the following conditions are satisfied:

• The TeamCity server and agents operate on the 64-bit Windows OS. If you need to use a 32-bit OS, you need to install and use 32-bit Java to run TeamCity;

• If the TeamCity server has manually configured memory settings (the TEAMCITY_SERVER_MEM_OPTS environment variable is defined), the value of the -Xmx parameter should be increased (recommended to twice the previous value). Before increasing the value, make sure the machine has enough physical memory for that.

• If you use Microsoft SQL Server as the TeamCity database with the integrated MS SQL authentication, the 64-bit sqljdbc_auth.dll native library has to be present in the due location.

• If there was any custom logic executing native tools on the server, check that it still works with the new process bitness.

The Running Builds Node is discontinued. In a multinode setup, you can instead configure a secondary node with the "Processing data produced by running builds" responsibility.

TeamCity now can automatically manage the amount of memory used by the git fetch process.
If you have previously used the teamcity.git.fetch.process.max.memory internal property to set the memory amount available for fetching in each VCS root, you can now disable it to delegate the detection of memory consumption to the TeamCity server. To control the limit of available memory, use the teamcity.git.fetch.process.max.memory.limit property.

• Bundled IntelliJ IDEA has been updated to version 2019.3.

• Kotlin, used in TeamCity DSL, has been upgraded to version 1.3.60.

• The Docker client in the TeamCity Linux agent image has been upgraded to version 19.03.3 to prevent the problems with unexpected Docker stop (see the related Docker issue).

• Docker Compose has been updated to version 1.24.1.

• Bundled dotCover and ReSharper CLT have been upgraded to version 2019.2.3.

• When using versioned settings, build history can be lost on importing settings from VCS. Details.

• The bundled ReSharper Command Line Tools (Inspections and Duplicates Finder) have been upgraded to version 2019.2.1.

• When using versioned settings, build history can be lost on importing settings from VCS. Details.

• If you use the .NET Core ("dotnet") steps on Windows agents, you can get the ".NET SDK was not found" error if you have .NET Core runtime (not SDK) installed on the agent in the location like C:\Program Files (x86)\dotnet. As a workaround, set the env.DOTNET_HOME parameter to the location of .NET Core SDK.
  See the related issue for details.

• The bundled IntelliJ IDEA has been updated to 2019.1.3.

• The bundled ReSharper tools (Inspections and Duplicates Finder) have been upgraded to 2019.1.0-eap08d version.

Tags are now mandatory for all Amazon instances run by TeamCity, which helps identify them. If you use integration with Amazon EC2, make sure to add the ec2:CreateTags resource-level permission in Amazon.

Starting with 2019.1, the behavior of reverse.dep parameters has been changed, and this change can affect your existing builds. In versions prior to 2019.1, when a build chain is triggered, TeamCity only took into account the reverse.dep parameters specified in the top-most build of the chain, i.e. in the build which depends on all other builds. If some intermediate builds of the chain had reverse.dep parameters, they were ignored.
After this fix this is no longer the case. Now, when a build chain is triggered, all reverse.dep parameters specified in all nodes of the build chain will be processed.

Agent tools (located under the <agent_installation>/tools directory on agents) are now transferred to an agent not on the agent upgrade, but right before the first build that uses the respective tool. You might need to update the build configuration settings so TeamCity knows which tools are required by the builds.
Before starting a build on an agent, TeamCity checks for the references to teamcity.tool.<tool_ID> configuration parameters to collect the set of tools used by the build. If some tool is referenced via this parameter, TeamCity will make sure this tool is present on the agent before the build logic starts executing.
If some of your builds use tools on agent assuming their locations under the <agent installation>/tools directory, such references should be changed to a TeamCity-provided parameter reference. Paths like <agent_installation>/tools/<tool_ID> used in TeamCity settings should be changed to the %teamcity.tool.<tool_ID>% parameter reference. For example, ../tools/maven3.4.5/bin/mvn should be replaced with %teamcity.tool.maven3.4.5%/bin/mvn.

The requirements for the .NET Framework version used by ReSharper tools have changed. Now, if you use ReSharper tools (dotCover and ReSharper Inspections) of version 2018.2 or newer (including the version bundled with TeamCity 2019.1) in your build configuration, the requirements to build agents will change to .NET Framework 4.6.1 or newer. Make sure to update .NET Framework on agents.

On upgrading to 2019.1, the Token-Based Authentication module will be enabled by default, so you can generate access tokens and start using them right away.

Now TeamCity web UI uses more restrictive value for the Content-Security-Policy HTTP header. This provides extra security at the expense of prohibiting usage of the web resources not hosted on the TeamCity server.
If you rely on external resources (for example, in the build report tabs content or by using not yet updated plugins), you can specify new header value in the teamcity.web.header.Content-Security-Policy.protectedValue=<full_header_value> internal property (and teamcity.web.header.Content-Security-Policy.adminUI.protectedValue property for the web pages in Administration area). Plugins can use ContentSecurityPolicyConfig open API interface to add to the value configured.

The dotCover.dcvr hidden artifact is no longer published by default. It is now created in the build temporary folder and removed when the build finishes.
If you use dotCover and rely on this artifact, specify the path to the %system.teamcity.build.tempDir%\..\agentTmp\dotNetCoverageResults\dotCover.dcvr file explicitly in the Artifact paths.

• The latest JaCoCo version (0.8.4) has been added to TeamCity.

• The bundled .NET tools (dotCover and ReSharper CLT) have been upgraded to the latest released version, 2019.1.1.

• JDBC drivers for external databases suggested on the fresh TeamCity installation have been updated to the following versions:

  • MySQL - 8.0.16

  • MSSQL - 7.2.2

  • PostgreSQL - 42.2.5

If you have been using beta versions of PowerShell, make sure to remove all beta versions earlier than v6.0.0-beta.9 before installing any new released PowerShell version. Due to updates in the PowerShell detector, if the old beta version is installed, TeamCity will use it instead of the new released one.

If you use Docker images and Windows Server 2019 with process isolation, build agents may fail to start (read more in Known Issues). To work around the issue, grant the "Full control" access to the "Authenticated Users" group.

Running builds are not shown on the build configuration page if there are no finished builds. To workaround the issue, stop the TeamCity server, replace the TEAMCITY_DIRECTORY/webapps/ROOT/js/ring/bundle.js with the bundle.js file attached to this issue and start the server.

• If upgrade fails with an error in MoveCustomDataStorageToDatabaseConverter or MoveRepositoryStateToCustomDataStorageConverter, apply workaround from the issue.

• If you're using Subversion externals from the same repository, you may face an issue with incorrect revision detection. A workaround for the problem is described in this issue.

• If you see OutOfMemoryError during TeamCity startup with org.jetbrains.dokka in stack trace, set the internal property teamcity.kotlinConfigsDsl.docsGenerationXmx=768m (as described in this issue)

• The bundled .NET Tools (dotCover and ReSharper CLT) have been upgraded to the latest released version, 2018.1.4

• TeamCity 2018.2 comes bundled with IntelliJ IDEA 2018.3.1. The IntelliJ IDEA Project Runner uses JPS 2018.3.1

• OpenJDK is bundled in the Windows .exe TeamCity distribution instead of Oracle Java.

The parameters that were previously used to reference the global NuGet feed are removed. After upgrading, all of them will be converted to the parameters referencing the default NuGet feed in Root project.

If you're still using deprecated NuGet feed references in project parameters please update them as following:

• Builds which are running while the server upgrades to 2018.1.4 can get their build log and status truncated, not duly reporting build failure. The build log gets warning with "__tc_longResponseMarker" text (details). It is recommended to wait till there are not running builds when upgrading to this version.

Support for Microsoft Internet Explorer 10 is discontinued in TeamCity 2018.1.4.

The latest JaCoCo version (0.8.2) has been added to TeamCity.

If you use JaCoCo coverage and you decide to downgrade from TeamCity 2018.1.3+ to TeamCity versions 2018.1 - 2018.1.2, you may experience issues requiring manual fixes to make the affected configurations work again.

If you are using tcWebHooks third-party TeamCity plugin, update it to the latest version before upgrading (details).

We increased accuracy for recognizing similar TeamCity exit code build problems. The existing investigations and mutes for these build problems will be reset.

The bundled Tomcat has been updated to version 8.5.32.

If you're upgrading from 2018.1 to 2018.1.1 and you want to see the NuGet packages missing due to issues TW-55703 and TW-55833, do the following:

• Clean-up .teamcity/nuget/packages.json files in the build artifacts. Consider using this PowerShell script:

> cd "%TeamCityDataDir%\system\artifacts\"
> Get-ChildItem -Recurse | Where-Object { $_.FullName -match '\.teamcity\\nuget\\packages\.json' } | Remove-Item

• On the Administration | Diagnostics | Caches page, reset the "buildsMetadata" cache and wait while re-indexing is finished. To temporary increase indexing speed, see the following tip.

Since 2018.1.1 TeamCity has multiplatform Docker images marked by the latest and version number tags published in Docker Hub, for example, jetbrains/teamcity-server or jetbrains/teamcity-server:2018.1.1. This allows using the same Docker image reference for Linux and Windows docker containers: see TW-55061 for details.

While publishing NuGet packages into the TeamCity NuGet feed in multiple build steps, only the packages published by the first build step will be visible. See TW-55703 for details. If you experience problems with download of NuGet packages published within archives see TW-55833.

Names of the Build Configuration parameters are now validated in more strict manner. While already existing parameters should continue to work, it is highly recommended to review the names and use Latin letters and no special symbols. Details

If you have Built-in authentication enabled with the "Allow user registration from the login page" setting on, the setting will be disabled on upgrade. If you need the registration, make sure the server is not open to unauthorized users access (e.g. not accessible from Internet) and enable the setting via the health item displayed at the top of the administration pages or in the "Administration | Authentication" under the "Built-in" module settings.

• The IntelliJ IDEA Project Runner uses JPS 2017.3.4 requiring Java 1.8 as the minimal version.

• The bundled ReSharper CLT and dotCover have been updated to version 2018.1.2

• Configuration of the NuGet feed was moved from the server level to the project level: now each project can have its own feed. The "NuGet packages indexer" build feature can be added to build configurations whose artifacts should be indexed.

• The following NuGet feed-related build parameters are deprecated:

  • teamcity.nuget.feed.auth.server

  • teamcity.nuget.feed.server

  • system.teamcity.nuget.feed.auth.serverRootUrlBased.server

  You now need to explicitly specify the URL from the NuGet Feed page in the Project Settings.

• The enabled default NuGet feed with all published packages accessed by URL /app/nuget/v1/FeedService.svc/ is now moved to the Root project feed /app/nuget/feed/_Root/default/v2/. It is recommended to switch to new URL in your projects.

• .nupkg files are now indexed on the agent side instead of the server which could slightly increase the time of builds for projects with the NuGet Feed feature and the automatic package indexing enabled or for builds with NuGet Packages Indexer build feature.

REST API uses version 2018.1. The previous versions of the API are still available under /app/rest/2017.2, /app/rest/2017.1 (/app/rest/10.0), app/rest/9.1, /app/rest/9.0, /app/rest/8.1, /app/rest/7.0, /app/rest/6.0 URLs. It is recommended to stop using previous APIs URLs as we are going to remove them in the following releases.

The Visual SourceSafe plugin is no longer bundled with TeamCity but is available as a separate download. Please contact our support, if you still use this VSS for your builds.

• Commit Status Publisher supports Gerrit 2.6+ versions. For support for older Gerrit versions, please turn to our support.

• When upgrading from TeamCity versions before 9.1, if TeamCity 2018.1 starts and agents are upgraded, but then you decide to roll back the server to the previous TeamCity version, the agents will not be able to connect back to the old server and will need to be reinstalled manually.

• Make sure that no HTTP requests from the agents to the server are blocked (e.g. requests to .../app/agents/... URLs)

• Since 2018.1, TeamCity uses the full project name with "/" instead of "::" as the separator for Project - Subproject wherever the full project name is present.

In all the build configurations, the builds run before the upgrade will not be reused in the chains and will run anew (only the last build on the default branch is affected if branches are used). This may also result in a clean checkout in the first run build for VCSs like Perforce. The behavior is similar to that after VCS root editing.

Security

When upgrading to 2017.2.x versions (please ignore when upgrading to 2018.1 and further versions): It is recommended to add "teamcity.artifacts.restrictRequestsWithArtifactReferer=true" internal property to enhance security of the server.

(Fixed 2017.2.3) If you use the Artifactory plugin and get the "Invalid RSA public key" browser message on opening build step settings, please apply the workaround.

Under Windows, when TeamCity server is started as a service, "logs\teamcity-winservice.log" file is not created and server startup errors are nowhere to be seen. Details

It is highly recommended to update the IDE plugins for all users to the latest version and then add the teamcity.uploadPersonalPatch.requireAuthorization=true internal property to enhance security of the server.

Since TeamCity 2017.2.2, the field which specifies the path to p4 works only on the agent side, for agent-side checkout.

For the server, the p4 binary should be present in the PATH of the TeamCity server (or can be specified via the teamcity.perforce.customP4Path internal property). The teamcity.perforce.p4PathOnServerWhitelist internal property can be used to specify a semi-colon-separated list of allowed p4 paths. The paths from this list can be set in VCS Root p4 path parameter for the server side (to restore old behavior).

Since TeamCity 2017.2.2, a number of Mercurial VCS root properties change their behavior for security reasons.

• the "HG command path" is used on the TeamCity server only if included into the whitelist

• the "Clone repository to" property is hidden if the VCS root doesn't have it already and is ignored by default. To make TeamCity display the property in all VCS roots, add the teamcity.hg.showCustomClonePath=true internal property. The value of the VCS root property is respected only if it is included into the whitelist specified by the teamcity.hg.customClonePathWhitelist internal property, which is a semi-colon-separated list of directories where a clone is allowed. Use /path/to/dir/* to allow clones to the child directories of the /path/to/dir.

• the "Mercurial config" is ignored on the server. If you need to enable some Mercurial plugins, please do that in the global .hgrc on the TeamCity server machine.

The versions in pom.xml were updated: kotlin.version is updated to 1.2.0, teamcity.dsl.version is updated to 2017.2.1. The dependency on kotlin-stdlib is replaced with the dependency on kotlin-stdlib-jdk8 in order to provide access to additional functionality available in jdk8 (e.g. named groups in regexps). The dependency on the deprecated kotlin-runtime and the redundant dependency on kotlin-compiler-embeddable were dropped.

Now TeamCity provides a parent maven project for Kotlin DSL which defines the teamcity.dsl.version and kotlin.version properties. With such a parent project, you will not have to update your pom.xml after eachTeamCity upgrade.

The easiest way to apply these changes is to run the 'Download settings in Kotlin format' action in project admin area and use the pom.xml from the zip produced by theTeamCity server.

The bundled Java used in Docker images has been updated to 8u151.

(Fixed 2017.2.1) TFS in Java working mode (when Team Explorer is not installed on the machine) report "TFS subsystem was destroyed" errors. See TW-52685 for details.

Upgrading using Windows installer can take significant time if your TeamCity installation directory contains lots of nested directories (e.g. TeamCity Data Directory is under it). The long stage can occur after "Extract: Uninstall.exe..." progress message. In you encounter this long step, please wait for the completion of the operation (the installer runs icacls.exe utility as a nested process). To prevent the issue it is recommendd to move the Data Directory out of TeamCity server installation home.

There is a breaking change which requires your action if you use Perforce streams with enabled feature branches and you're using a non-default branch filter.

Starting from TeamCity 2017.2, Perforce VCS Roots use the same format for Perforce streams and TeamCity feature branches specification.

In the VCS Root branch specification for Perforce, +:stream_name must now be replaced with +://stream_depot/stream_name. Also, for better presentation of stream names in the UI, you may want to replace the default branch specifications like +:* with +://your_stream_depot/*.

This change was made in the scope of fixing TW-48038.

Now if the server process is stopped unexpectedly or killed, the process will automatically restart. The server should be stopped using the teamcity-server.bat/sh stop command which performs a graceful stop.

REST API uses version 2017.2. The previous versions of the API are still available under /app/rest/2017.1 (/app/rest/10.0), app/rest/9.1, /app/rest/9.0, /app/rest/8.1, /app/rest/7.0, /app/rest/6.0 URLs.

buildType entity

has "templates" sub-element now instead of "template" to support multiple templates.

build entity No longer expose boolean "running" attribute, textual "state" attribute with value "running" is used instead.

Windows XP and Vista are no longer the supported versions of Windows for the TeamCity Server and Agent. While the server and agent will still most probably work on these old versions, we do not target the versions during our development. Let us know if the support for the versions is important for your TeamCity usage or you find any issues with the systems support.

J2EE Servlet container version 2.5 is not supported since TeamCity 2017.2. TeamCity does not guarantee support for Tomcat 6.x and Jetty 7.x implementing Servlet 2.5. For .war distribution (not recommended, .tar.gz distribution is recommended), TeamCity supports Apache Tomcat 7+, J2EE Servlet 3.0+ and JSP 2.2+.

• The bundled Tomcat 8.5. restricted usage of special characters in the URL including curly bracket symbols ({ }). Details.

• TeamCity integration with Intellij-based IDEs no longer supports StarTeam and Visual Source Safe version controls.

TFS Personal support lists all build configurations for TFVC VCS root. See TW-51497 for details.

Editing cloud profile cancels all builds on profile agents. See TW-49616 for details.

Since 2017, TeamCity adopts the common JetBrains versioning scheme that identifies versions by year following the pattern: <year>.<number of the feature release within the year>.<bugfix update number>. The current version is TeamCity 2017.1 formerly known as TeamCity 10.1.

In this version TeamCity settings format has been changed and if your settings are stored in Kotlin DSL, you might need to update Kotlin DSL scripts before continuing to use them. Check any related server health reports after the server upgrade.

TeamCity now implements CSRF protection to improve web UI security and this introduces several changes in behavior which might affect your installation. In particular:

• If you use a reverse proxy before TeamCity, the proxy should not change the original "Host" request header (this typically requires configuring the proxy to set the Host header to the original request value). Also, it should not modify the "Origin" and "Referer" headers present in the original request. While this has been the recommended setup for a long time, now it becomes critical for the TeamCity web UI functioning;

• if you use non-bundled clients which perform HTTP GET requests to TeamCity, some of the GET requests (those which change the state of the server, like http://server/action.html?add2Queue=XXX) stop working in 2017.1, please change the requests to use POST instead of GET;

• the non-browser clients which reuse authentication by supplying the TCSESSIONID cookie with the request, need to be updated to supply the "Origin" HTTP header with the value the same as the host the request is being sent to. If the check fails, you get the HTTP 403 response with the details of the failed check. The details are also logged into teamcity-auth.log.

The old (TeamCity 6.0) IPR runner has been removed from the TeamCity. It was deprecated and has not been offered as an option since TeamCity 6.0, and now it is gone completely (the corresponding build configurations will not run anymore).

It is recommended to overwrite the server's conf\teamcity-server-log4j.xml file with the content of the conf\teamcity-server-log4j.xml.dist file which represents the default logging configuration which has changed in this release. If you do need a custom logging configuration, consider using logging presets instead of modifying conf\teamcity-server-log4j.xml.

The same overwriting from the sibling .dist file is recommended for the TeamCity agents.The conf\teamcity-*-log4j.xml.dist file is created after the first start of the upgraded TeamCity version.

Builds metadata storage will be re-created and builds will be reindexed right after the upgrade. As a result, immediately after the upgrade, the TeamCity internal NuGet feed will not contain all of the packages.During the builds reindexing, the following messages may appear in the teamcity-server.log:

INFO - .index.BuildIndexer (metadata) - Enqueued next 100 builds for indexing, builds left: 2000, last build id: 3813
INFO - .index.BuildIndexer (metadata) - Enqueued next 100 builds for indexing, builds left: 1900, last build id: 3713

"builds left:" indicates the number of builds left to process. Note that TeamCity starts reindexing from the most recent builds, so all fresh builds should appear in the TeamCity NuGet feed in a relatively short time.

To increase the metadata indexing speed you could use the following tip.

REST API has only minor changes, so the same API is exposed under the app/rest/10.0 and /app/rest/2017.1 URLs. API version has been updated to 2017.1 though to reflect the changes.The build's node "triggeredBy" now has more correct values of "type" attribute for the builds started after 2017.1 upgrade. In particular, the "buildType" value is not used anymore, the"finishBuild", "snapshot", etc. values are used instead.

As a workaround could be used ReSharper web installer. See TW-51680 for details.

When %dep.ID.NAME% parameter reference is used and there are several dependency paths to the same build configuration with id "ID" so that different builds are accessible via (direct or indirect) artifact dependencies, the result of the reference resolution could have used any of the builds without any guaranteed precedence.

Since 10.0.4 dep. parameter resolution works as follows:

1. if there is a snapshot dependency, the build from the same chain wins.

2. if there is no snapshot dependency and several builds are accessible via an artifact dependency, the build with a greater buildId wins. If there are several artifact dependencies from a single build configuration, only the first one is considered.

AWS SDK has been updated to 1.11.66 to support new instance types (r4.4xlarge, f1.16xlarge, t2.2xlarge, t2.xlarge, r4.2xlarge, r4.xlarge, r4.large, r4.16xlarge, r4.8xlarge, f1.2xlarge).

The behavior of EBS optimization, enabled by default since TeamCity 10.0, is changed similarly to what EC2 console offers:

1. EBS optimization is turned on by default for c4.*, m4.*, and d2.* (non-configurable).

2. EBS optimization is turned off by default for any other instance types.

3. EBS optimization can be turned on for instances that support it (such as c3.xlarge) by checking the appropriate box when configuring the image of the Amazon cloud profile.

The bundled dotCover has been updated to version 2016.2.2

(fixed in 10.0.2) TeamCity server temp folder can fill up if an agent tool is installed as a directory in <TeamCity Data Directory>/plugins/.tools. Details and workaround.

(These known issues are fixed in 10.0.1)

TeamCity agents before version 10 used to report DotNetFramework4.0_* properties whenever any of 4.x versions of .NET framework were installed on the agent. Since TeamCity 10, DotNetFramework4.0_* properties are reported only when 4.0 runtime (without updates) is installed. For 4.5.*, 4.6.* updates corresponding DotNetFramework4.N_* properties are reported. This change in behavior allows for more precise requirements definition.

If after the upgrade you get incompatible agents with Unmet requirement: Exists=>DotNetFramework4.0_x86(/x64) exists message, review the explicit requirements in your build configuration. If your build is compatible with any .NET 4.x runtime (it is a most common case) please use Exists=>DotNetFramework4.*_x86(/x64) requirement. If you would like to run on .NET 4.5+ agents - use Exists=>DotNetFramework4.(5|6).* requirement.

Some third-party plugins are known to be affected. On the upgrade, make sure to upgrade xUnit plugin to version 1.1.2+

During upgrade TeamCity will optimize data in the ignored_tests table (we do that in order to speedup the TeamCity built-in backup / restore process). In some rare cases, when this table contains millions of rows, the process of table optimization may take significant time - possibly a few hours. Among other data, the table contains the reasons why a particular test in a build was marked as ignored. If this information for old builds is not very important for you, you can start TeamCity server with the additional JVM option: -Dteamcity.truncateIgnoreReasonConverter.copyReasons=false

In this case TeamCity will not copy the ignore reasons into the new, optimized table, and this particular step of the upgrade process will run much faster.

Starting from TeamCity 10, the TeamCity server requires Java 8 JRE/JDK (included in the Windows .exe distribution).

TeamCity agents currently require Java 1.6+, but starting from the next TeamCity version, the minimum requirement for the Java on the agent will be Java 8 (included in agent's Windows .exe distribution). It is recommended that you now consider upgrading the agents Java.

Java memory options change

It is recommended to remove the "-XX:MaxPermSize=..." JVM option from TEAMCITY_SERVER_MEM_OPTS environment variable, if previously configured. (This is due to the fact that Java 8 does not use permanent generation (PermGen) anymore)

Agent requirements and artifact dependencies can be disabled now. TeamCity plugins and REST API- based code using a version of API prior to TeamCity 10 is likely to ignore the disabled status of these settings.

TeamCity comes with cross-platform TFS integration: to work with TFS, you no longer need to install a TeamCity server on a Windows machine.

Visual Studio Online Work Items plugin is obsolete since TeamCity 10.0 and can be safely removed. TeamCity 10.0 has a built-in integration with Team Foundation Work Items which supports TFS 2010+ and Visual Studio Team Services. After upgrade, TeamCity will detect the existing issue tracker connections of this plugin and convert them into TFS Work Items.

The default setting for the VCS checkout mode on creating new build configurations has changed: now TeamCity will check out the sources on the agent before the build. If the agent-side checkout is not possible, TeamCity will use the server-side checkout. Explicit server-side or agent-side checkout is still in place. The new default applies only to newly created build configurations; all the existing ones will work as configured before.

New TeamCity installations now have different agent management permissions assignments: Project Administrator role does not include (global) Agent Manager role. Instead, Project administrator role has agent-project permissions which allow managing agents from the agent pools with only projects where user has Project Administrator role.

Existing installations are not affected by this change in order not to change the user permissions. However, it is recommended to review the Project Administrator role and consider excluding "Agent Manager" role and adding the following permissions:

• Enable / disable agents associated with project

• Start / Stop cloud agent for project

• Change agent run configuration policy for project

• Administer project agent machines (for example, reboot, view agent logs)

• Remove project agent

• Authorize project agent

The legacy version of the TeamCity Visual Studio Add-in is no longer supported. Visual Studio 2005 and 2008 are not supported.

TeamCity Visual Studio Add-in is shipped as a part of ReSharper Ultimate. After installation, the TeamCity Add-in will be available under the RESHARPER menu in Visual studio.

Note that the installer will remove the pre-bundle products versions: TeamCity and ReSharper versions prior to 9.0, dotCover prior to 3.0, dotTrace prior to 6.0.ReSharper Ultimate does not support the Visual Studio versions 2005 and 2008.

IntelliJ IDEA 12.1 and older, as well as other IntelliJ-based products released prior to year 2013, is no longer supported by IntelliJ Platform Plugin.

After the server upgrade, the builds used as snapshot dependencies may be rebuilt once even if the snapshot dependency has the "Do not run new build if there is a suitable one" option set to ON. This is done to fix the issue.

Clean checkout will be enforced in builds with Stream-based and Client-based Perforce VCS Roots.

Starting from TeamCity 10, TeamCity does not accept by default connections to SVN servers accessed by https:// protocol with non-trusted server SSL certificate. To enable access with such certificates, you should either import the certificate to server JVM keychain, or enable VCS Root option "Accept non-trusted SSL certificate" (Enable non-trusted SSL certificate in 10.0) (issue).

Ant runner: the bundled Ant distribution has been upgraded from 1.9.6 to 1.9.7

.NET dotCover coverage: the bundled dotCover is updated to 2016.1

ReSharper command line tools: the bundled R# CLT is updated to 2016.1

Java inspections and duplicates: the bundled IntelliJ IDEA is updated to 2016.2

If you were using the TeamCity-GitHub third-party plugin prior to TeamCity 10.0, you can safely remove it: the built-in TeamCity integration will detect the existing connection to GitHub issue tracker and pick up your settings automatically.

Configuration parameters teamcity.tool.NuGet.CommandLine.%NUGET_VERSION%.nupkg are not reported anymore. The teamcity.tool.NuGet.CommandLine.%NUGET_VERSION% parameters should be referenced instead.

For example, instead of using %teamcity.tool.NuGet.CommandLine.DEFAULT.nupkg% parameter reference %teamcity.tool.NuGet.CommandLine.DEFAULT% should be used.

Several statistic values (metrics) has been reworked and renamed:

• BuildCheckoutTime into buildStageDuration:sourcesUpdate

• BuildArtifactsPublishingTime into buildStageDuration:artifactsPublishing

• ArtifactsResolvingTime into buildStageDuration:dependenciesResolving

Old keys are still supported in charts definitions.

REST API uses version 10.0. The previous versions of the API are still available under /app/rest/9.1,/app/rest/9.0,/app/rest/8.1, /app/rest/7.0,/app/rest/6.0 URLs.

Requests for a set of items with the locator addressing a single item which resulted in 404 responses previously will now return an empty set as a more consistent approach. For example, .../app/rest/builds?locator=id:<non-existent build id>. REST debug logging might have diagnostics message with more details as to the case.

Requests for set of items may return not all/incomplete results (with zero or more items included) and provide nextHref sub-element with the link to retrieve the next "page" of items. The search result is complete when no nextHref sub-element is provided.

Some requests for set of items (e.g. .../app/rest/vcs-roots and .../app/rest/vcs-root-instances) will use paged results by default when queried without a locator (they used to list all the items). Add the "count:NNN" locator dimension to set page size.

Finding builds (.../app/rest/builds/... URL)
When performing builds scan to find those matched by the locator specified, by default for performance reasons TeamCity will return partial result limited by scanning only 5000 most recent builds. To process a larger portion of the history, check the nextHref attribute returned or set the lookupLimit locator dimension to a larger value.
Previously, until specifically requested the builds from non-default branch as well as canceled, personal and failed to start builds were not returned. Now these filtered out builds are returned by default for running and queued builds queries as well as when filtering by agent or user. Use defaultFIlter:true/false locator dimension to manage the default filtering explicitly.
Also, number:NNN locator now adheres to the same default logic: only "usual" finished builds from default branch are searched by number and several builds can be returned if found.

Finding VCS roots (.../app/rest/vcsRoots/... URL)(minor)
A VCS root locator with project and buildType specified used project as the context for finding buildType. This is no longer the case,the buildType locator should be full one to find the build configuration.

Build Configuration's Artifact Dependencies (entities returned by.../app/rest/buildTypes/... URL)
The artifact-dependencies sub-element of the buildType element now uses textual generated ids instead of numeric ones which depended on the order previously. This also affects requests for artifact dependencies modification.
The agent-requirements sub-element of the buildType element now uses generated ids instead of the parameter name as id. This also affects requests for agent requirements modification.

Editing agent requirements (.../app/rest/buildTypes/.../artifact-requirements/... URL)
Previously, on adding a new agent requirement for the same parameter, the existing one was overridden by the new one; now a new one is added. Previously, on adding a new agent requirement, the parameter name was derived from the id attribute of the agent-requirement node. Since TeamCity 10, the parameter name is derived from the "property-name" property.

Test and problem occurrences (.../app/rest/testOccurrences,.../app/rest/problemOccurrences URL)
The sorting of the returned results is changed for some of the queries compared to the previous versions. For example, the "../app/rest/testOccurrences?locator=build:(xxx)" request now returns the tests in the order they were run in the build.
Previously, test occurrences were sorted by the new status and then by name. Problem occurrences were sorted by problem id.
Also, the build dimension in the test/problem-related locators now supports multiple builds so for the requests which matched several builds via the "build" dimension, all the builds will be processed; previously only the first matching build was processed.

Entities
The property entity used to have its "own" Boolean attribute indicating whether the parameter is redefined in the build configuration as opposed to inherited from a template/project. Now the attribute is renamed to 'inherited' and its value is inverted.
The vcs-root and vcs-root-instance used to have status and lastChecked attributes. Now VCS root instance has status element (with current node which has status and and timestamp attributes) and VCS root does not have the data as it produced undefined results in case of several VCS root instances.
The test entity id became Sring instead of Long (due to inability to represent some Java Long value in JavaScript)

Build type and template
The settings node used to contain all the supported settings. Now only those defined in the build configuration or template are present. The same is true for .../app/rest/buldTypes/XXX/settings/* requests: only the values changed from defaults are present.

Compatible agents
When querying for compatible agents, only the agents which can actually run the builds are now returned. By default, unauthorized, disconnected and disabled agents are not listed. This behavior differs from that in previous versions which had a number of discrepancies. Affected requests and entities: .../app/rest/agents?locator=compatible:(...); ../app/rest/agents/.../compatibleBuildTypes and incompatibleBuildTypes; nested nodes Agent.compatibleBuildTypes, QueuedBuild.compatibleAgents, BuildType.compatibleAgents.

There is a known issue in the bundled dotCover run on Windows XP and Vista. You can use the hotfix or the workaroundprovided. The issue will be fixed in the next dotCover release.

There is a known issue with NuGet Credentials not working for the Authenticated Feed URL of the internal TeamCity NuCet server on the local agents. As a workaround, instead of using %teamcity.nuget.feed.auth.server%, please specify the external server URL in the build step and the build feature.

NuGet versions prior to 2.8.6 require .Net Framework 4.0+ installed on the build agent, NuGet 2.8.6 and later requires .NET 4.5.

Since version 9.1.6, TeamCity does not support NUnit 3 beta versions (released before NUnit 3.0.0).

The "Run a process per assembly" option of the NUnit runner has been removed from NUnit 3 settings. Configure the desired behavior using the required command line options in the corresponding field.

Bundled IntelliJ IDEA updated to version # 143.1945 (roughly equivalent to 15.0.3 with a few additional fixes).

Bundled version of Maven 3.2.x updated to 3.2.5.

Note on permissions: to monitor performance of a build agent run as a Windows service, make sure the user starting the agent is member of the Performance Monitor Users group.

There is a known issue in the bundled dotCover run on Windows XP and Vista. You can use the hotfix or the workaround provided. The issue will be fixed in the next dotCover release.

JetBrains product icons are updated in accordance with the new JetBrains branding.

Since TeamCity 9.1.5, git sparse-checkout is disabled by default. To enable it in a TeamCity project, add the teamcity.git.useSparseCheckout=true parameter to this project.

Gradle runner system.* properties, introduced in TeamCity 9.1.2, defined for the build as JVM's system properties of the Gradle process, will not work since 9.1.5. Now the TeamCity system properties can be accessed in Gradle scripts as Gradle properties (similarly to the ones defined in the gradle.propertiesfile) and are to be referenced as follows:

a) name allowed as a Groovy identifier (the property name does not contain dots): customUserProperty
b) name not allowed as a Groovy identifier (the property name contains dots, e.g. build.vcs.number.1): project.ext["build.vcs.number.1"]

The bundled JetBrains IntelliJ IDEA (IDEA inspections and duplicates) has been updated to version 15.0.2

JetBrains ReSharper command line tools (.NET inspection and duplicates) have been updated to match ReSharper 10.0.2 releaseTeamCity Visual Studio Add-in Web installer updated to ReSharper 10.0.2 releaseBundled JetBrains dotCover updated to version 10.0.2

Certain roles/permissions configurations can result in error loading roles and no ability for regular users to view projects. In such cases the "Circular reference is detected between roles" critical server error is displayed on the server administration pages for those logged in as server administrator. Please check the workaround for the issue.

Git agent-side checkout may malfunction (details at TW-43202) when the teamcity.git.use.native.ssh=true parameter is specified in a build configuration or in the agent config. To fix that, install the #snapshot-34 build of the Git-plugin.

Git agent-side checkout works incorrectly with git client versions 1.7.0-1.7.4: the checkout directory contains files only, all directories are missing (details at TW-43330). To workaround the problem, add the teamcity.git.useSparseCheckout=false parameter in the Root TeamCity project.

Since 9.1.4 the TeamCity Windows binaries are signed with SHA-2 code-signing certificate following the Microsoft SHA-2 policies. This means that on systems prior to Windows XP SP3, the executables will not pass code signing verification; newer Windows systems require the corresponding security update from Microsoft.

Bundled Oracle JRE (in both Server and Agent.exe installers) has been updated to version 1.8.0_66 (32-bit)

JetBrains ReSharper command line tools (.NET inspection and duplicates) have been updated to match ReSharper 10.0 release

TeamCity Visual Studio Add-in Web installer updated to ReSharper 10.0 release

Bundled JetBrains dotCover updated to version 10.0

There is a known issue in the bundled dotCover 3.2 which could cause a build's failure with the following exception: "System.Security.VerificationException: System.Security.VerificationException: Operation could destabilize the runtime". The issue is fixed in dotCover 10.0 bundled with TeamCity 9.1.4 release.

Bundled JVM (Server Windows installer and Agent Windows installer) is updated which results in disabled SSL RC4 chiper suite for outgoing HTTPS connections. For example this makes connections to CloudForge SVN servers non-functional with "SSLHandshakeException: Received fatal alert: handshake_failure" error. (details)

Changes from 9.1.1 to 9.1.2

The Command line runner can fail to execute a custom script if it has a non-default hashbang specified at the beginning of the script: TW-42498

When using Amazon EC2 cloud integration, an AMI-image, containing build agent versions 9.1.2-9.1.5 will appear twice with name EC2-i-abcdefgh and EC2-i-abcdefgh-1 consuming 2 licenses. To fix the issue please use an AMI-image with agent 9.1.6+. Just updating server to 9.1.6 won't help, if AMI remains the same. (details)

Build status icons updated to a more "standard" look and are of a bit larger now.

JetBrains ReSharper command line tools (.NET inspection and duplicates) have been updated to match ReSharper 9.2 release

TeamCity Visual Studio Add-in Web installer updated to ReSharper 9.2 release

Bundled JetBrains dotCover updated to version 3.2

Bundled Oracle JRE (in both Server and Agent .exe installers) updated to version 1.8.0_60 (32-bit)

Bundled Ant distribution has been upgraded form 1.8.4 to 1.9.6. Note that Ant build steps using bundled Ant will use another version of Ant after the server upgrade. Ant 1.9.6 requires Java 1.5 at least, so builds using Ant and running under Java 1.4 will stop working.

MSTest runner is merged with VSTest console runner (previously provided as a separate plugin) into the Visual Studio Tests runner. Note that after upgrade to TeamCity 9.1, MSTest build steps are automatically converted to the Visual Studio Tests runner steps, while VSTest steps remain unchanged.

note

If you have used VSTest.Console runner plugin, make sure that you have latest version (build 32407) installed. The plugin version can be viewed on Administration | Plugins List page. Earlier versions of this plugin are not compatible with TeamCity 9.1 and may cause malfunction of .NET related build runners which can manifest with java.lang.NoSuchMethodError: jetbrains.buildServer.runner.NUnit.NUnitVersion.parse(Ljava/lang/String;) build errors. The plugin can be downloaded from its page. Consider migrating your vstest.console execution steps to the bundled Visual Studio Tests runner.

TeamCity agent automatically detects the installed MSTest and used to expose the locations in system.MSTest.N.N system properties.

Since TeamCity 9.1, the locations are exposed via teamcity.dotnet.mstest.N.N configuration parameters. Check TW-41845 for a workaround if you cannot easily change the properties usage.

Previously TeamCity supported a case when one test could have been reported from within another test using service messages. Now, after the fix of TW-40319, starting another test finishes the currently started test in the same "flow". To still report tests from within other tests, you will need to specify another flowId in the nested test service messages.

REST API uses version 9.1. Previous versions of API are still available under /app/rest/9.0, /app/rest/8.1, /app/rest/7.0, /app/rest/6.0 URLs.

Finding builds
Summary (tl;dr): Some build filtering rules has subtle changes. Most importantly, a queued build can now be returned instead of 404 when searching by build id and meaning of the "project" locator dimension has changed to be not recursive. Also, failed to start builds are now not included until "failedToStart:any" locator dimension is specified.

Details:
Affected requests: /app/builds/<locator>..., /app/builds?locator=<locator>, /app/buildTypes/<btLocator>/builds and others with build locator

locator: id:<number> or taskId:<number>

• previously, if the matching build was a queued one, 404 (Not Found) was returned

• now the queued build is returned

locator: project:<id>...

• previously, all the builds belonging to build configurations of the project and all it's subprojects (recursively) were found

• now only the builds belonging to build configurations of the project specified are found. For finding the builds recursively, use "affectedProject:<id>." dimension. This makes the usage consistent with build type locators.

locator: tag:<text>

• previously, when "<text>" used ":" character, that used to treat the entire "<text>" as tag name

• now the "<text>" is parsed as a nested locator. For searhing tags with ":" character, locator "tag:(name:(<tag>))" should be used

locator: <text>

• previously, if <text> is not a number, response was 400 (Bad Request) with "LocatorProcessException: Invalid single value: '<text>'. Should be a number." message.

• now search by build number across all builds on the server is performed (this is not recommended to be used on production servers). For not found builds 404 (Not found) response is returned

locator: id:<number>,xxx:yyyy

• previously, build was found by id "<number>, other dimensions were ignored

• now if the build found by id does not match other dimensions, response is 404 (Not Found)

locator: agent:<agentLocator>

• previously <agentLocator> was used as is, without applying any defaults (unauthorized agents were included until specifically excluded)

• now <agentLocator> has the same behavior as in /app/rest/agents request: unauthorized agents are excluded by default

Finding projects
Searching project by name used to return 404 error is several projects were matched. Now will return the first project found.

Build's artifacts
There are several bugs fixed in listing build artifacts via /app/rest/builds/<locator>/artifacts/* requests which can cause subtle changes in the results for the request. Check the new behavior if you relied on the response.The most important changes are:

• the initial path specified via URL part is searched for without current locator value, it will not generate 404 responses until there is no such artifact on disk.

• archives are not treated as directories (do not have children elements) by default. Specify "browseArchives:true" to treat archives as directories (in "recursive:true" mode only one level of archives is treated as directories)

Agents
Agents which are not known to the system (which were deleted) used to have id "-1". Now "id", "pool" and some other entries are no longer included for such agents.

Experimental support for Xcode 7 has been added.

Due to API changes, third party issue trackers integration plugins might not be compatible with TeamCity version 9.1. Old plugins will not work and will report "java.lang.NoSuchMethodError: jetbrains.buildServer.issueTracker.AbstractIssueProviderFactory.<init>(Ljetbrains/buildServer/issueTracker/IssueFetcher;Ljava/lang/String;)V" error in teamcity-server.log log (more details in the issue). If you observe such errors, please contact the plugin authors. If you are the author of affected plugin, please refer to the related notes in Open API Changes.

If you have enabled versioned settings for projects which use meta-runners in TeamCity 9.0, on upgrade and following commit into the settings VCS root, the meta runners will be deleted from the server. Workaround is to commit the meta-runners definitions into the settings repository manually. Related issue: TW-39519.

Due to missing support for national character sets (nvarchar) in Oracle 10.x JDBC drivers, TeamCity 9.0.1 will ask to upgrade Oracle JDBC drivers to the latest version. The minimal supported version of Oracle JDBC driver is 11.1.

• If you have custom artifact clean-up rules configured which mention ".teamcity" directory, build logs can be deleted by the clean-up procedure. Make sure you have build logs backup before upgrade and remove all the custom artifacts cleanup rules with ".teamcity". Related issue: TW-40042. This issue is fixed in 9.0.3 release.

• If you use Microsoft SQL Server database with TeamCity, after the scheduled clean-up background run, TeamCity UI pages can lock until the server restart. See TW-39549 for details. This issue is fixed in 9.0.2 release.

• If you use LDAP authentication on the server and there are lots of login attempts on the server (e.g. there is an active REST-using script), OutOfMemory errors can occur and require server restart. Consider installing an LDAP plugin with a fix from the issue. This issue is fixed in 9.0.1 release.

• If you have large Maven projects, you can see builds failing with OutOfMemoryError. This is caused by update of back-end embedded Maven to 3.2.3 which has bigger memory footprint. Consider increasing Build Agent memory limits Related issue: TW-41052

Since TeamCity 9.0, disk-stored XML settings definitions of projects, build configurations and VCS roots have unique non-human-readable id (uuid) stored. These ids are automatically generated and are assumed to globally unique. On settings files copying, you need to change/make unique not only id (file name) and name (across siblings) of the entity , but also remove it's uuid from the file. TeamCity will generate new uuid automatically.

The location of the build logs in the internal format stored under TeamCity Data Directory has changed. The build log files in internal format are now stored under hidden build artifacts.Namely, the location has changed from system/messages/CHyy/xxyy.* to system/artifacts/<PROJECT EXTERNAL ID>/<BUILD CONFIGURATION NAME>/xxyy/.teamcity/logs/buildLog.*.

Old build logs are migrated to the new location on TeamCity server startup (TW-37362). To avoid this migration, teamcity.skip.logs.migration internal property should be set before server startup.

On the first server start after upgrade from a version prior to 9.0, the server will reindex all builds for the purpose of builds search functionality and NuGet feeds. During the indexing time, some builds will not be available in the search results and in NuGet feeds. The server can also behave in less performant manner way during the indexing. teamcity-server.log has corresponding logging. On indexing finishing, there are "BuildIndexer (search) - Finished re-indexing builds" and "BuildIndexer (metadata) - Finished re-indexing builds" lines in the log.

Since TeamCity 9.0, the issue trackers are configured on the project level instead of the global server-wide configuration.On the server upgrade, all existing issue tracker integrations are moved to the Root project, which makes them still accessible to all the projects on the server.

Since 9.0, TeamCity tries to establish WebSocket connections between the browser and the server for the UI updates. If you have a proxy server (like nginx) in front of the TeamCity web UI, make sure that the proxy is configured properly to support WebSocket connections.

If the proxy is misconfigured or does not support the WebSocket protocol, a server health item will be shown for TeamCity system administrators. In this case TeamCity will use plain old polling for the UI updates as before.

REST API uses version 9.0. Previous versions of API are still available under /app/rest/8.1, /app/rest/7.0, /app/rest/6.0 URLs.

• Change bean: the webLink attribute is renamed to webUrl to match other beans (TW-34398).

• Sub-elements representing empty collections in some of the beans are no longer included into responses (used to be included as an empty tag in XML).

• the builds changes element does not include the "count" attribute by default (for performance reasons), count can still be included by providing fields parameter like: "fields=$long,changes(count,href)"

• The /app/rest/agents request now returns all the authorized agents by default (used to include unauthorized connected agents as well)

• queued builds now have the id attribute instead of the taskId attribute (they are the same for new builds since TeamCity 9.0)

Build tags-related changes
The /app/rest/builds/<buildLocator>/tags build request now returns a different XML: <tags count="1"><tag name="TAG"/></tags> instead of <tags><tag>TAG</tag></tags>.
The same applies to the /app/rest/buildTypes/<buildTypeLocator>/<buildTypeLocator>/buildTags request.
The same change in the structure also applies to the build's entity nested "tags" element.

To create a tag, there is an old way to post a plain-text tag name to the app/rest/builds/<buildLocator>/tags URL.
When sending POST or PUT XML or JSON requests to the URL, the new XML format is to be used (<tag name="TAG"/></tags> instead of <tag>TAG</tag>).

In TeamCity 9.0, multiple tests with the same name within the same build are considered a single test with an invocation count. If any of these test runs fail, the whole test is considered failed in the build. The related issue is TW-24212.

This change results in drop of test number counters in builds which have multiple runs for the same test. If you have a build failure condition which relies on test number in the build, this change may affect you.

If you need the tests to be treated as separate ones, consider running them in the test suites with different names or otherwise changing the test/running logic to change the full test name displayed in TeamCity.

The national character sets (nchar, nvarchar, nclob types) for text fields are now supported in MS SQL databases used by TeamCity. It is recommended to use the Microsoft native JDBC driver, as jTDS JDBC driver does not support the nchar and nvarchar characters. If you still use jTDS, please migrate.

Upon upgrade and entering the normal working status, TeamCity starts a background process to move the entries from the vcs_changes database table to vcs_change table. This process is transparent and you can continue working with the server as usual. It has negligible impact on the server performance and the only affected logic is the projects import feature (it is recommended to be used only with backups taken after the process is completed). The progress of the process can be seen on the Backup section in the server administration, along with "TeamCity is currently optimizing VCS-related data in the database for better backup/restore performance" message.
The other important thing is that the data copying increases the size of the raw database storage.
If this is an issue for your case (e.g. it might be with Microsoft SQL Server database with set database size limit), it is recommended to ensure the database size limit is twice the current size before the upgrade. It is possible to perform database-specific procedures to shrink the storage to match the actually stored data after the VCS changes migration process finishes.

The Git and Mercurial VCS roots no longer provide the ability to specify a custom clone path on the server for new VCS roots. If you need this ability, set the following internal properties to true for git and mercurial respectively: teamcity.git.showCustomClonePath, teamcity.hg.showCustomClonePath.

The TeamCity Add-in installed as a part of ReSharper Ultimate will remove the pre-bundle products versions: TeamCity and ReSharper versions prior to 9.0, dotCover prior to 3.0, dotTrace prior to 6.0.

Besides, it will not use the settings provided by the 8.1 version. The traditional add-in downloaded from TeamCity server can still use settings from previous version.

TeamCity agent installation via the Java web start installation package is no longer available.

The change in behavior introduced in 8.1 (see below) has been fixed. Command line runners using "Executable with parameters" option which were created/changed with TeamCity 8.1 can expose a change in behavior with the upgrade. The recommended approach is to switch to "Custom script" option instead of "Executable with parameters" in command line runner.

VSTest console runner is no longer bundled with TeamCity and is available as a separate plugin. For download details, see the plugin page

When installing TeamCity anew and creating an MS SQL database with integrated security using the database setup UI, you may receive an error. We are planning to resolve it in the next bugfix, meanwhile use the following workaround:

1. After receiving the error, stop the TeamCity server.

2. Start the TeamCity server.

3. On the database configuration screen, fill out the required information. Do not use the Refresh button. Make sure the information specified is correct.

4. Continue with the configuration steps.

If for some reason the workaround above does not resolve the problem, do the following:

1. Start the TeamCity server, approve a new database creation, configure the MS SQL access with a login and password, without integrated security.

2. Ensure that TeamCity works properly.

3. Stop the TeamCity server.

4. Modify the Setting up an External Database file: configure MS SQL connection string to use integrated security, and remove the login and password.

5. Start the TeamCity server again.

A new "VSTest.Console" runner which first appeared in TeamCity 8.1 is in experimental state and is not recommended for production use at this time. It will not be present in TeamCity 8.1.x by default (will be available as a separate download).

PowerShell runner plugin is broken in 8.1. Fix is available, please follow instructions in issue comment.

Command line runner using "Executable with parameters" option can process quotes (") and percentage signs (%) in a bit different way then in previous TeamCity versions (see details in the issue). To switch back to the previous (8.0) behavior you may specify command.line.run.as.script=false configuration parameter in a build configuration or in a project. The issue is fixed in 8.1.1.
The recommended approach is to switch to "Custom script" option instead of "Executable with parameters" in command line runner.

If you have not switched to 64 bit JVM yet and use -Xmx1300 memory setting for the server and the server is running on Windows, consider decreasing the setting to -Xmx1200 as otherwise you might encounter "Native memory allocation (malloc) failed" JVM crash. See the recommended memory settings for details.

Some actions has moved under the "Actions" button available at the top-right of the page, near Run button.
These include:"Label this build sources" on Changes tab of a build,
"Pause", "Copy", "Move", "Delete", "Associate with Template", "Extract Template", "Extract Meta-Runner" on build configuration settings administration page,
"Copy", "Move", "Delete", "Archive", "Bulk edit IDs" on the Project Settings administration page.

Action "Create Maven build configuration" is no longer available. Most of its functionality is covered by create project from URL and create VCS root from URL pages.

The build.triggeredBy and build.triggeredBy.username configuration parameters provided by the plugin added by the plugin are now available without the plugin under teamcity.build.triggeredBy and teamcity.build.triggeredBy.username names respectively. Consider migrating to the latter set of parameters in your settings if you used the plugin's ones.

If the build takes lock on all values of a resource with custom values, these values are provided as lock values in build parameters. Corresponding issue: TW-29779

The following internal properties define free disk space thresholds on the TeamCity server machine:

• teamcity.diskSpaceWatcher.threshold set to 500 Mb by default displays a warning on all the pages of the TeamCity web UI.

• teamcity.pauseBuildQueue.diskSpace.threshold set to 50 Mb by default pauses the build queue. The teamcity.diskSpaceWatcher.softThreshold property is removed.

The PowerShell plugin now uses the version that was specified in the UI as the -Version command line argument when executing scripts. Corresponding issue: TW-33472

The latest version of the API has not changed, it is still "8.0" while there are changes in the API detailed below. If you find this inconvenient for your REST API usages, please comment in the corresponding issue.

Entities returned in the response of REST API requests might now exclude attributes/elements with empty/default values. This is relevant for boolean fields with "false" value and empty collections. The recommended approach is to make sure the client code assumes "false" as a value for not present boolean attributes/elements.

"projectName" of buildType node now contains full project name (with the names of the parent projects) instead of the short name of the project.

In the lists of builds, "startDate" attribute is not longer included in the "build" node. It has become an element instead of attribute to match the full build data representation. If your REST API usage is affected, check a way to get that element in a request for the list of builds.

Requests /app/rest/buildTypes/XXX/parameters/YYY and /app/rest/projects/XXX/parameters/YYY now support "text/plain" and "application/xml" responses. To get plain text response (which was the only supported way before 8.1) you will need to supply "Accept: text/plain" header to the request.

Password properties of the VCS roots are now included into the responses, just without values.

CCTray-format XML (app/rest/cctray/projects.xml) does not include paused build configurations now.

Response to the experimental request /app/rest/buildTypes/XXX/investigations has changed the format and got additional fields to cover tests and problem investigations. There is an internal property rest.beans.buildTypeInvestigationCompatibility to include removed sub-items. Please let us know via support email if you need to use the internal property.

Dropped support of Subversion 1.4-1.6. Now only Subversion 1.7-1.8 working copies formats supported.

First Clean-up after server upgrade might take a bit more time then regularly if there are many builds on the server. Following clean-ups will then run a bit faster then in previous versions.

This version introduces user-assignable IDs for projects and build configurations. This new ID is now used instead of internal id (projectN and btNNN) in at least:

• URLs of the web pages and artifact downloads

• in REST API

• project IDs are also used in directory names on the server under <TeamCity Data Directory>\system\artifacts instead of project names used prior to TeamCity 8.0

If you used any of the above, please, verify if you are affected by the change.
Learn more about IDs at Identifier.

On upgrade, all the projects get automatically generated IDs based on their names.
Build configuration IDs are set to be equal to internal (btNNN) ids and can be later changed from the Administration UI via the Regenerate ID or Bulk Edit IDs actions.

Please note that the names of the projects and build configurations are no longer unique server-wide (are only unique within the direct parent project) and can contain any symbols which might be relevant if you used these in directory or file names.

The format of the project settings storage on the disk under <TeamCity Data Directory>/config has been changed.
If you used any tools to read or update project-config.xml files, you will need to update the tools. It is recommended to use REST API or TeamCity open API (Java) to make changes so that the tools are not hugely affected by the format change.

In version 8.0 build configuration templates support project hierarchy and TeamCity uses new rules:

• The TeamCity administration UI limits the use of templates only to those from the current project and its parents. On copying a project or a build configuration, the templates which do not belong to the target project or one of its parents are automatically copied.

• TeamCity no longer allows attaching a build configuration to a template if the template does not belong to the current project or one of its parents.

• Before version 8.0 it was possible to extract templates from a build configuration of one project to an unrelated project or to associate a build configuration in one project with a template in another. After upgrade to TC 8.0, such templates will become inaccessible in the current project. To reuse build configuration templates from an unrelated project, it is recommended to manually move them into the common parent project (or the Root project if you want them to be globally available).

The agent no longer reports system properties which come from the agent JVM: system.os.arch, system.os.name, system.os.version, system.user.home, system.user.name, system.user.timezone, system.user.language, system.user.country, system.user.variant, system.path.separator, system.file.encoding, system.file.separator).All the aforementioned parameters are now reported as configuration parameters with the teamcity.agent.jvm. prefix instead.If you used any of the parameters, make sure you update them to the new values.

IntelliJ IDEA project runner now uses IntelliJ IDEA's external make tool to build projects. Since this tool requires Java 1.6 to work, IntelliJ IDEA project runner now requires Java 1.6 (at least) too.

Build configurations with feature branches now process clean-up rules per-branch which can result in more builds preserved during clean-up than in previous versions. See details.

TFS now prefers Team Explorer 2012 to Team Explorer 2010 (if both are installed) for TFS operations

If you use JetBrains YouTrack and use its TeamCity integration features, please note that only YouTrack version 4.2.4 and later are compatible with TeamCity 8.0.
If you need earlier YouTrack versions to work with TeamCity 8.0, please let us know.

External ids There are changes in the API related to the new external ids for project/build types/templates as well as other changes.
The old API compatible with TeamCity 7.1 is still provided under "/app/rest/7.0" URL.

If you used URLs with locators having "id" for projects, build configuration or templates (like .../app/rest/projects/id:XXX or .../app/rest/buildTypes/id:XXX), please, update the locators to one of the following:

• (recommended) "id:EXTERNAL_ID" (you can get the external ID in web UI URLs or via a request to .../app/rest/projects/internalId:OLD\_ID/id

• just "ANY_ID" to find the entity either by its internal, external id or name (use with caution: you can find more than you expect)

• "internalId:INTERNAL_ID" to find the entity by the internal idYou can also use the "/app/rest/7.0/" URL prefix instead of "/app/rest/" to work with 7.0-version of REST API which still uses internal IDs except for finish build trigger properties.

Also, it is possible to set the internal property rest.compatibility.allowExternalIdAsInternal=true to turn on the compatibility mode so that id:xxx locators will search also by the internal id. Note that this will be dropped in the future versions of TeamCity and is not recommended for use.

Other Changes
Requests for builds ".../builds/<locator>/..." and ".../builds?locator=<locator>" no longer return personal and canceled builds by default. To include those, make sure you add ",personal:any,canceled:any" to the locators.

The "relatedIssues" element of the build entity no longer contains a full list of related issues. It has only the "href" attribute whose value can be used to get the related issues via a separate request.
There is also an internal property "rest.beans.build.inlineRelatedIssues" which can be set to true to return the "relatedIssues" node back for compatibility. See TW-20025 for details. Also, the ".../builds/xxx/related-issues" URL is renamed to ".../builds/xxx/relatedIssues".

The "source_buildTypeId" property is dropped from snapshot and artifact dependency nodes. Instead, the "source-buildType" sub-element is added with a reference to the build type.
Creating dependencies is still supported with the "source_buildTypeId" property, but is deprecated. There is an internal property "rest.compatibility.includeSourceBuildTypeInDependencyProperties" which can be set to true to include the "source_buildTypeId" property back.

In version 8.0 VCS roots support project hierarchy:

• When creating a VCS root, the project element should always be provided now. The element supports the locator attribute to specify the project.

• the shared attribute is dropped from the VCS root: after upgrade, such VCS roots are attached to the root project (with the "_Root" ID) and become globally available.

• when copying projects and build configurations, the shareVCSRoots attribute is no longer present. To make the VCS root available to projects and build configurations, move it to the parent/root project and then proceed with the copying.

It is recommended to create projects hierarchy which corresponds to organizational/settings sharing structure and move the VCS roots to most nested umbrella projects. Users then can be granted "Create / delete VCS root" role in the project to be able to edit VCS roots. Please note that users can edit a VCS root only if it is used in the projects they have "Edit project" permission for.

The "template" attribute in a build configuration template node is renamed to "templateFlag".

PUT for /users/<locator>/roles and /userGroups/<locator>/roles now accepts list of roles as it should and replaces existing roles instead of accepting single riles and adding it.

Many of PUT and POST requests which used to return nothing now return the entities created.

See details

If you used the Shared Resources plugin with TeamCity 7.1.x, make sure to remove it as it is now bundled. See the upgrade instructions.

If you used the QueueManager plugin, make sure to remove it as it is now bundled. See the upgrade instructions

Maven bundled with TeamCity upgraded to version 3.0.5.

If your agents connect to the TeamCity server by HTTPS protocol, and after upgrade agents fail to connect with error messages like:javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure

then you should change Tomcat SSL connector configuration, i.e. add the following attribute to SSL connector and restart TeamCity server:sslEnabledProtocols="TLSv1,SSLv3,SSLv2Hello"

The issue only manifests when the server runs under Java 1.7.

See also:

• http://mail-archives.apache.org/mod_mbox/tomcat-users/201302.mbox/%3C512559F7.4080001@gmail.com%3E

• http://youtrack.jetbrains.com/issue/TW-30221#comment=27-561843