What's New in TeamCity 2021.1
Kotlin Script build runner
Kotlin by JetBrains is a widely adopted and concise programming language. It works on all platforms supported by TeamCity and is perfect for scripting build tasks. To meet the high demand for such a tool in TeamCity, we've designed a new Kotlin Script build runner.
You can use it to automate recurring routines, such as custom checks, sending service messages, or downloading files via HTTP. If you use Ant or Command Line build steps and are eager to try Kotlin instead, the new runner gives a great opportunity to do this. You can rewrite tasks in Kotlin and just switch the existing build steps to the new runner.
To configure a Kotlin Script build step, enter a script code or provide a path to it. By default, TeamCity will run it using Kotlin 1.5.0, but you can install any other compiler version in Administration | Tools.
Read this article for more details.
Node.js build runner
To improve your experience with building JavaScript projects in TeamCity, we introduce a dedicated build runner for Node.js. It allows running npm, yarn, and node commands inside your builds and reporting detailed test results.
You can add the Node.js steps manually or let TeamCity scan your project's repository. When scanning, TeamCity will parse the package.json file to see what frameworks are used in the project. Based on this information, it will propose adding the respective build steps: for example, to install necessary dependencies or to run tests. You can later adjust these steps as you like.
If there are ESlint, Jest, or Mocha dependencies in your project, TeamCity will show the respective test results right in the build overview.
To configure a Node.js build step, just enter a script with necessary Shell commands:
Currently, all Node.js steps are run inside a Docker/LXC container, which means Docker or Podman needs to be installed on build agents. TeamCity uses the node:lts version by default; but if there is an .nvmrc file inside your project, it will search for the image specification there.
Read this article for more details.
Customize automatically triggered builds
Build triggers now support custom parameters. This feature has been anticipated by our users, as it makes automatically triggered builds as versatile as builds started in the custom run mode.
There are limitless combinations of how you can use this instrument to autorun different builds within the same configuration. Most importantly, the same script can now deploy triggered builds to different targets, depending on preconditions like a source branch or launch time.
In a build trigger's settings, you can find the new Build Customization tab with the following options:
General Settings: choose to delete all files in the checkout directory if you need to start every triggered build with clean sources.
Build parameters: customize the value of any parameter used in the current build configuration. Or, add a new parameter, and it will be available only in builds started by this trigger. You can even use it to override a parameter of a dependency build configuration: use the
reverse.dep.<dependencyBuildID>.<property>syntax for this.
This feature gets even more effective if you combine it with our build step execution conditions. You just need to add a parameter-based condition to a step and then configure two triggers: one will run builds with this step (when the condition is satisfied) and one — without it. A popular use case is to run an extra clean-up step when a failed build is restarted with a retry trigger: this can help solve many build problems even without involving a user.
Multinode setup improvements
One of the top priorities of TeamCity is to provide a high-availability solution for your building processes. In this release, we bring multiple updates that make it easier to configure a performant and stable cluster setup.
Switch node from secondary to main in runtime
Now, if the main node goes down for any reason, its main role and all the respective responsibilities can be promptly assigned to another server.
By default, the new " Main TeamCity node " responsibility belongs to the current main server, but it gets vacant if this server becomes unavailable. You can then assign it to any secondary server in Administration | Nodes Configuration.
The assigned server becomes the main node and automatically receives all its other responsibilities (processing builds, managing agents, and so on). This new main node keeps all its running builds, and the agents reconnect to it automatically if a proxy is configured in your setup.
When the previously main server starts again, it becomes a secondary node, as the " Main TeamCity node " responsibility is already occupied by another server. If necessary, you can repeat the procedure above to switch roles between these servers.
External proxy as load balancer
In the previous versions of TeamCity, build agents had to send all the requests to the main node, and the main node was redirecting these requests to a suitable secondary node. If the main were to go down, the agent would not be able to communicate with its appointed secondary node. Starting with version 2021.1, TeamCity supports a new approach — using proxy as a balancer of requests between all clients (build agents and TeamCity users) and nodes.
This approach allows routing all agents to the proxy instead of the main server. This will make the server-agent communication less dependent on the main node and get your setup closer to 100% availability. Besides, since agents won't connect to the nodes directly, you can configure and maintain HTTPS settings in one place — on the proxy level.
See more details and the example proxy configuration in this article.
Manage max number of builds on secondary node
If a secondary node is assigned to processing builds, it is now possible to limit the number of parallel builds it can run. Previously, if the " Processing data produced by running builds " responsibility was enabled for a node, it would process all builds. Now, you can distribute the load between multiple nodes or even keep some builds assigned to the main node.
To configure the limits, go to Administration | Nodes Configuration, find the required node in the list, and click Edit next to its " Processing data produced by running builds " responsibility. In the Limit builds dialog, enter a relative limit of builds allowed to run on this node. We suggest that you set the limits depending on the nodes' hardware capabilities.
If the maximum limit of allowed builds is reached on all secondary nodes, TeamCity will be starting new builds on the main node — until some secondary node finishes its build.
New search mode based on Elastic
Alternatively to the local Lucene-based search, TeamCity now provides a search mode based on Elasticsearch. Both modes allow searching builds by number, tag, and many other parameters. The main difference is in the search index location: it can be stored next to the TeamCity server or on your Elastic host.
The new mode has two advantages: (1) it saves disk space on the TeamCity server machine and (2) it is better for the TeamCity performance. It is especially effective for multinode installations, as nodes spend fewer resources on maintaining a single remote index than on multiple local indexes.
For relatively small installations, you may continue using Lucene search, with no need to reconfigure anything.
You can select the search mode on the Root project level in Project Settings | Builds Search. To connect to your Elastic host or cluster, enter its URL and credentials.
After you save the new settings, TeamCity will spend some time reindexing builds. The exact duration depends on the size of your server. You can track or control the progress in the Diagnostics table.
Read-only project settings
Versioned project settings is one of the most popular features of TeamCity. We keep adding more controls to this functionality based on your feedback: since this version, you can make project settings read-only in the TeamCity UI.
When the synchronization of a project's settings is enabled, all changes made in the UI are committed to the settings repository, and vice versa. But in some cases, it might be convenient to prohibit editing settings via the UI. For example, if you store a project settings in the same repository with its source code, you might want to track and approve all changes entirely by the means of VCS. Or, if you import settings from a read-only branch and then change them in the UI, TeamCity will fail to commit back to the repository and, therefore, apply new changes made in the VCS.
To address these and any similar cases, we've added a new option: Allow editing project settings via UI. If you disable it in a project, this will make this project's settings read-only in the UI and prevent TeamCity commits to the settings' repository.
To toggle the new option, go to Project Settings | Versioned Settings | Configuration:
Read this article for more details.
Limit permissions of access tokens
You can now create access tokens with limited permissions and use these tokens for REST API requests. This gives you more control over how your scripts integrate with TeamCity. For example, if used in combination with the timeout setting, this allows generating short-lived tokens for specific tasks.
By default, a token's Permissions scope is set to " Same as current user ". It means that the created token will grant the same permissions as those of the current user. You can use such a token both for authentication in the UI and for REST API requests.
If you change the scope to " Limit per project ", you will be able to limit the token's access to a certain project and even select particular permissions for it. The list of available projects and permissions depend on your user role. Tokens with a limited scope can only be used for REST API requests.
Perforce support improvements
This release brings multiple improvements for projects versioned in Perforce.
Perforce client in Linux Docker images
Linux Docker images of TeamCity agent and server now come with a Perforce client.
Simplified setup of post-commit hooks
Post-commit hooks allow reducing the number of polling operations and offloading the TeamCity and VCS servers. In the previous versions, it was required to maintain several hooks for Perforce. Now, you can easily configure a single post-commit hook for the entire Perforce depot. To do this, follow this instruction in our documentation.
Support ChangeView specification
TeamCity now supports the ChangeView specification in Perforce clients and understands the @revision syntax in the import statements of streams' definitions.
Moreover, if a Perforce VCS root is set to the Client mapping mode, you can use the ChangeView specification to limit the root's scope to a particular revision or multiple revisions. To do this, open the settings of a Perforce VCS root, choose the Client mapping connection mode, and enter the client mapping. For example:
where 90 is the number of the exact revision of dir1 and automaticLabelWithRevision is the labeled revision of dir2. All the other revisions of these directories will not be monitored by this VCS root.
Clean up stream workspaces on Perforce server
TeamCity allows using Perforce streams as feature branches. To optimally process changes in such streams, it needs to create and maintain dedicated workspaces on the Perforce server. Over time, these workspaces might consume a significant amount of resources on the Perforce server's machine. Besides, if you want to close a task stream, you won't be able to do this if there is a workspace associated with it. Both of these problems can be solved by deleting no longer necessary workspaces. Previously, there were no means to clean them up automatically, and any manual cleaning would require involving a Perforce server administrator. With the new Perforce Administrator Access connection, project administrators can clean workspaces right from the TeamCity UI.
To configure this, go to your project settings in TeamCity and, under Connections, add a new connection with the Perforce Administrator Access type. Enter the host and user credentials for accessing the Perforce server (the user must have the admin permission), and TeamCity will connect to it.
During every clean-up, TeamCity will detect and delete workspaces that have been inactive for more than 7 days. Or, you can delete them anytime by clicking Delete these workspaces in the connection settings. Note that workspaces are deleted only on the server — not on build agents — and only if they were created by TeamCity.
If the support for feature branches is enabled in a Perforce root, it is also possible to delete workspaces associated with any stream available to this root. Go to Build Configuration Home, open the Actions menu, and click Delete Perforce stream workspaces. By default, this action is available to all users with the Project Developer role. In this menu, you can specify a path to a stream, and TeamCity will delete the related workspaces on the Perforce server.
Onboarding UI assistant
TeamCity has a rich user interface, and some of its numerous handy features might not be obvious to beginners. To help our new users navigate around the interface, we introduce the onboarding UI assistant.
To enable it, open the Help menu in the upper right corner of the screen and click Show Hints. You can hide them anytime by closing the assistant menu.
To see a hint for a certain element, hover over its name in the assistant menu. Some hint names also provide a 
link to the related documentation.
Hints are available for experimental Project Home, Build Configuration Home, and Build Overview, as well as for some of the Settings pages.
Experimental UI improvements
Our experimental UI is a work in progress: we introduce its features in the early stages of development so you can already benefit from them. In each release, we polish already existing pages and reproduce all the important classic features in the new UI.
The experimental UI roadmap strongly depends on our users' feedback. In version 2021.1, we've focused on improving the Build Overview page: read below about a tree mode for tests and a new code coverage visualization. We've also adjusted the design of the Project Home page based on your requests.
Show tests in tree mode in Build Overview
Test results are often the most important information you seek when opening the build details. We keep improving how tests are represented in our experimental UI: our goal is to reproduce all instruments available in the classic UI and make them even handier for you. Now, the new UI supports the test tree mode in the Build Overview.
In the Tests block, click Show grouped tests, and TeamCity will represent them in a tree mode, grouped together by project → build configuration → test suite → test package → test class. You can switch between the tree and flat structure anytime, depending on your current tasks.
As tests within the same group have a similar purpose, you might want to quickly select them all or temporarily collapse them to focus on other groups. The tree mode works great for that, and it is especially helpful if there are many tests in your build configuration. When a group is selected, you can apply actions like Investigate or Mute to all its tests at once.
If you prefer a keyboard navigation, use Up and Down keys to navigate the tree and Space to collapse or expand the selected group or test.
New code coverage preview
TeamCity can provide code coverage for multiple build runners. With this release, the code coverage preview in Build Overview gets even more visual.
If coverage is available for a build configuration, you can quickly preview a visualized statistics of the build's tests and see how it changed compared to the previous build:
Refined Project Home
After gathering your feedback on the experimental Project Home page, we focused on two tasks: use the space on this page more effectively and make a project tree easier to navigate. We hope that the refined page will serve you as a handy dashboard for previewing and running all builds of the same project:
Restrict to customize builds with personal patches
TeamCity allows running a custom build with your local changes — without actually changing the common project's code stored in a VCS. To run such a build, you need to send the patch with changes to the TeamCity server: either by using a Remote Run in IDEs or by uploading it via UI or REST API. This patch will be delivered to the build agent machine and used only in the custom build. However, as the patch is stored on the agent file system, it would be wise to ensure that it includes only trusted changes, which cannot potentially harm the next builds running on this agent.
For this purpose, we've created a new user permission — Change build source code with a custom patch. On upgrading to 2021.1, it will be automatically enabled for the default Project Developer role and other roles with the Customize build parameters permission. By toggling this permission, you can granularly control who can patch builds or, if necessary, fully restrict this functionality in important projects.
Customize multipart upload of artifacts to Amazon S3
If you store build artifacts in Amazon S3, you can now control how they are uploaded. TeamCity uses a multipart upload of large files by default, but it is now possible to customize its parameters: upload threshold and upload part size. This can help use the network bandwidth more effectively and improve throughput.
Add multiple VCS triggers per build configuration
Now, you can add more than one VCS trigger to a build configuration. This is convenient if you want to trigger builds in the same configuration but according to different trigger rules and with different branch filters. This allows you to set a quiet period for builds in all branches except one — where a build will start as soon as a new change is committed. Or, you can configure a trigger to start builds on each check-in only in one given branch.
Choose checkout policy for Git roots
A Git VCS root has a new Checkout policy option. You can choose between four policies and get different benefits, depending on the lifecycle of your build agents.
The default policy is AUTO, which means the decision is always up to TeamCity. But, you can enforce a certain policy for a VCS root by choosing one of the other options:
Use mirrors: best for long-lived agents that run numerous builds. A repository mirror is kept on the agent, which speeds up the successive builds.
Do not use mirrors: simply fetch a repository in the build checkout directory, without creating a mirror. Less optimal in terms of disk usage and preserved for backwards compatibility with existing build configurations.
Shallow clone: best for short-lived agents (for example, disposable agents in the cloud). Fetches only a single revision necessary for one build. This can make the build start significantly faster, especially if the project repository has a long history of revisions.
Read this article for more details.
Viewing thread dump of process running inside a container
TeamCity allows viewing a thread dump of processes running on a build agent machine right in the Build Results. Now, you can view it even if the process runs inside a container (for example, with our Container Wrapper or Docker Compose functionality). For Windows containers, TeamCity shows Java processes and their thread dumps. For Linux containers, it shows all running processes and thread dumps for Java processes.
While the build is running, click View thread dump in its Overview.
TeamCity will show the structured information about the agent processes:
Quick access to build status widget
Our build status widget shows the status of the last build in a configuration. As the widget doesn't require authentication, you can feature the build status icon anywhere outside TeamCity: for example, on GitHub. Now, you can quickly access this widget from the Build Overview.
To access the widget menu from Build Configuration Home, open the Actions menu and click Get build status icon:
The Status Image menu shows the icon preview and allows copying its code in one of the supported formats:
You can embed this code into an external page and view the build status without opening TeamCity.
Other improvements
Cross-platform ReSharper Inspections and Duplicates Finder
ReSharper Inspections and Duplicates Finder now support the cross-platform mode and can be run inside Docker.
Setting .NET SDK requirements for build agents
The .NET build runner now allows setting a requirement to SDKs installed on a build agent. You can enter the list of expected SDK versions when configuring a .NET step, and TeamCity will automatically create agent requirements: the current build will only run on agents that have all the required SDKs.
Python runner updates
Marketplace plugin verification
TeamCity will check if every new plugin, installed from the JetBrains Marketplace, is signed with a valid certificate. This will ensure that the installed plugin is safe to use and its source code is intact.
Fixed issues
Upgrade notes
Before upgrading, we highly recommend reading about important changes in version 2021.1 compared to 2020.2.x.
Previous releases
Roadmap
See the TeamCity roadmap to learn about future updates.