TeamCity On-Premises 2023.11 Help

What's New in TeamCity 2023.11

Matrix Build

In TeamCity, you can leverage build parameters to replace raw values across build scripts, configuration/project settings, command-line arguments, and so on. Normally, each a parameter stores only one value. Starting with version 2023.11, you can add the Matrix Build feature to your configurations to specify a range of possible parameter values. When running such a configuration, TeamCity will spawn multiple builds to automatically cycle through these values.

Matrix Build setup

Adding multiple parameters, each with its own set of values, forms a matrix. TeamCity will run a build for each cell of this matrix, and report the results to the Overview page that allows you to identify at a glance which parameter/value combinations are failing.

Matrix Build Summary screen

The Matrix Build feature offers multiple pre-configured options that allow you to quickly set up your build configuration so that it runs in environments that differ by the installed operating systems, default Java versions, and architectures.

Learn more: Matrix Build.

Amazon Web Services Integrations

EC2 Plugin Update

We have overhauled the Amazon EC2 integration plugin. Apart from a refreshed look, the updated plugin features the following enhancements:

  • You can now create images that utilize Mac AMIs. Mac VMs can be run only on dedicated Mac Mini hosts that should be booked for at least one day. Using the updated TeamCity EC2 plugin UI, you can now specify tags to locate a suitable host.

  • You can now specify multiple instance types for a cloud image. This enhancement makes your cloud agent setups more versatile and reliable, and increases your chances to book a spot instance.

  • The Subnets field now accepts multiple values, which allows you to specify different sets of incoming and outgoing traffic rules.

  • The new Image priority setting allows you to range cloud images. When TeamCity needs to spin up a new cloud agent, it will prioritize an image with the highest priority number (given that this image has not yet reached its active agents limit).

  • TeamCity can now automatically choose Regions or Availability Zones in which your spot requests are most likely to succeed based on their spot placement scores. To allow TeamCity request and utilize these scores, add the ec2:GetSpotPlacementScores IAM permission.

Learn more: Setting Up TeamCity for Amazon EC2.

S3 Plugin Update

Version 2023.11 ships an updated S3 plugin that features the following enhancements:

Updated S3 Plugin
  • Intuitive and streamlined UI designed with both Amazon S3 buckets and S3-compatible storages (such as MinIO, Backblaze B2, and others) in mind.

  • Support for buckets with enabled Transfer Acceleration.

  • Hassle-free setup with the reduced number of settings. All connection-related properties are now retrieved from a selected AWS Connection. The AWS region is automatically obtained from the selected bucket.

  • The ability to disable integrity verification that TeamCity carries out by default for all custom S3 storages.

Learn more: Amazon S3 and S3-compatible Storages | Upgrade Notes

AWS Connection Improvements

New Available for sub-projects and Available for build steps settings in AWS connections allow you to ensure these connections are not used by unwanted TeamCity projects and features (for example, AWS Credentials or custom S3 storages).

Share AWS connections

In addition, you can now refer to the new section of our "Configuring Connections" documentation article to learn how to configure secure AWS connections that follow Amazon guidelines and do not require permanent user credentials: Recommended Setup.

Learn more: Amazon Web Services (AWS).

VCS Integrations


Seamless GitHub App Registration

In version 2023.05, we introduced the new type of connections to GitHub and GitHub Enterprise. These connections utilize GitHub Apps, instead of the traditional OAuth-based access to repositories.

Starting with version 2023.11, you will be able to create these connections much faster, without manually setting up and registering new apps in GitHub. Choose the Automatic creation mode in the Add connection dialog and TeamCity will do the rest.

GitHub Manifest App Button

Learn more: Configuring Connections.

Refreshable Tokens

You can now issue refreshable access tokens for GitHub App connections.

JetBrains Space

Automated Connections

With this release we introduce the updated hassle-free way to set up integrations between TeamCity and JetBrains Space projects. Instead of manually creating, setting up, and installing Space applications that grant TeamCity all required permissions, you can now delegate this routine to TeamCity. All you need to do is to point TeamCity to the right Space organization, and it will do the rest for you.

New Space Project Connection

The updated integration utilizes two types of connections:

  • Organization connection — creates a basic Space application that allows TeamCity to retrieve the list of projects in your organization and create new Space applications.

  • Project connections — use the parent organization connection to create applications that allow TeamCity to access individual Space projects.

Learn more: Configuring Connections.

Automatic Status Publishing

Starting with this version, TeamCity build configurations that target JetBrains Space repositories do not require a configured Commit Status Publisher build feature to post build-related updates. Set up a TeamCity project via a predefined Space connection and build statuses will be posted automatically.

Publish Space build statuses

The option to manually set up the Commit Status Publisher feature is still available for those who wish full control over the process, as well as for custom setups where TeamCity is unable to publish build statuses automatically.

Learn more: JetBrains Space.

Refreshable Tokens

You can now issue refreshable access tokens for JetBrains Space connections.


Reusing Sources on Cloud Agents

You can now reuse sources that are present on (or copied from) persistent storages mounted to your cloud agents. In previous versions this behavior was not possible for Perforce builds running on new agent machines.

Learn more: Reuse Checked Out Sources on Cloud Agents.

Perforce Helix Swarm Enhancements

In version 2023.11, we have overhauled the "Perforce Helix Swarm" publisher of the Commit Status Publisher build feature. TeamCity can now utilize workflows and tests that already exist in your Swarm setup (instead of creating its own tests). In addition, the Publisher no longer requires credentials of a user with administrator access.

Personal build in TeamCity

Learn more: Integration with Perforce Helix Swarm.


Commit Status Publishers and Pull Requests features that target GitLab repositories can now utilize refreshable application tokens to pass the authentication.

Acquire access token for GitLab

Bitbucket Cloud

Pull Requests features that track Bitbucket Cloud repositories have two new Authentication Type options:

  • Refreshable access tokens issued via corresponding OAuth connections.

  • Permanent access tokens issued for a specific repository, project, or workspace.

Learn more: Bitbucket Cloud Pull Requests.

Bitbucket Server and Data Center

The Pull Requests feature can now utilize refreshable OAuth tokens to access repositories on Bitbucket Server / Data Center.

Learn more: Pull Requests.

Azure DevOps

The Commit Status Publisher and Pull Requests build features can now pass authentication using refreshable tokens obtained from configured TeamCity connections.

Azure OAuth in CSP

Learn more: Commit Status Publisher | Pull Requests.


  • Build agents now report the DotNetWorkloads_<version> parameter that returns all .NET workloads installed on the agent machine. Learn more: Parameters Reported by Agent.

  • The .NET runner now provides the Excluded test assemblies setting for the vstest command. This field allows you to specify paths to files the command should ignore.

    Excluded assemblies for vstest
  • If your builds run a large amount of parallel tests in each batch, TeamCity can automatically switch to an alternative test filtering mode that reduces potential performance issues. See this article for more information: Alternative Test Filtering for .NET.

Schedule Custom Builds

You can now set a specific date and time when a build should run. To do this, invoke the Run Custom Build dialog and use settings from the new Date section.

Run custom build dialog, General Settings tab

Learn more: Run Custom Build.

Build Cache

The new Build Cache feature allows configurations to cache files required by builds (for instance, downloaded npm packages) and reuse them in consecutive builds. This technique assists build agents in offloading excessive operations and can significantly speed up your building routines.

Build Cache feature

In addition to sharing caches with its own future builds, a configuration that caches files can pass them to other build configurations within the same project.

Learn more: Build Cache.

Agents with Bundled JDKs

Starting with version 2023.11, you can build distributions of TeamCity agents bundled with custom JDKs. These distributions allow you to install both an agent and a JDK it requires to operate in one go.

Full agent distributions page

To create a custom agent distribution, navigate to Administration | Agent JDKs and add a new JDK option (you will need to specify the platform, the architecture, and a link for TeamCity to download this specific JDK).

Add Agent JDK

When a new option is added, TeamCity will start building your custom agent distribution. You can download custom agent+JDK bundles by clicking Install agent | Full distributions on the Agents | Overview page.

Learn more: Install TeamCity Agent.

Versioned Settings: Load Additional Settings From a VCS

Starting from this version, TeamCity can load custom snapshot dependencies, VCS roots and checkout rules from settings stored in a version control system. As a result, you now have even more flexibility to edit versioned settings and create custom branches with settings that significantly differ from those in default/stable branches.

When detecting these previously ignored settings, TeamCity dynamically creates required hidden entities (such as virtual build configurations) that are in effect only for the current build and remain hidden for other revisions/branches that use different settings.

5-Step Setup

To enable the updated behavior, tick the Apply changes in snapshot dependencies and version control settings option on your project's Versioned Settings page.

Learn more: Apply Changes in Snapshot Dependencies and Version Control Settings.

Access Parallel Builds' Artifacts from a Primary Build

When you run a build configurations that employs the Parallel Tests build feature, TeamCity splits a build into batches interconnected in an automatically generated chain. In previous version, artifacts produced during such builds were published in these individual batch builds, while a parent build had none.

Artifacts in parallel testing

As a workaround, you could switch to the Dependencies tab when viewing completed configuration builds.

Artifacts in parallel testing 2

Starting with this version, artifacts produced by batch builds are aggregated in the Artifacts tab of a main build. You can also use the parameter to arrange artifacts produced by batch builds into different directories.

Aggregated artifacts

Learn more: Publish Artifacts Produced By Batch Builds.

Step Statuses and IDs

Starting with version 2023.11, you can specify IDs for your steps (similarly to project and configuration IDs).

Step ID

TeamCity uses these IDs to generate new<step_ID> parameters that report the step exit statuses ("success", "failure", or "cancelled").

Step statuses

You can use these values to perform custom actions depending on the statuses of previous steps. For example, you can craft custom step execution conditions.

Learn more: Step Status Parameters.

Additional ReSharper Plugins for the Inspections Runner

The Inspections (ReSharper) runner now features the R# CLT Plugins field that allows you to add your favorite ReSharper plugins (such as StyleCop, CleanCode, or Unity Support) downloaded from JetBrains Marketplace or installed from a local storage.

ReSharper plugins list

Learn more: JetBrains ReSharper Command Line Tools Settings.

Service Messages

Added the new service message that allows you to track the contents of the given file and echo new lines to the build log.

Stream file to log

Learn more: Writing the File into the Build Log.


Move Configurations

You can now send a POST request to the following endpoint to move a build configuration to another project:


For example, the following request finds a build configuration with the "SourceProject_MyBuildConfig" ID and moves it to "MyProject2":


Wind Down Cloud Instances

Previously, you could send the DELETE request to a running cloud agent to terminate it.


Starting with this version, you can stop cloud instances via POST requests to the following endpoints:

/app/rest/cloud/instances/<cloudInstanceLocator>/actions/stop /app/rest/cloud/instances/<cloudInstanceLocator>/actions/forceStop

Use the ...actions/stop endpoint to issue a "soft" stop request: if the target agent is currently busy, it will stop after the build finishes.

The ...actions/forceStop endpoint allows you to stop a cloud instance even if it is busy.

Learn more: Start and Stop Cloud Instances.

Sakura UI and UX Enhancements

  • We have reworked the Agent Parameters tab. You can navigate to this tab when viewing any TeamCity agent to instantly check this agent's configuration and environment paramters and system properties.

    New Agent Parameters tab
  • You can now bookmark required agent pools to easily access them from the top of the agents and pools list.

  • The Dependencies Tab now displays a find panel that allows you to search for specific dependent builds by configuration names.

  • The Interactive Agent Terminal introduced in version 2023.05 now opens in a panel docked to the bottom of an agent details or build results page. You can move it to a separate browser tab by clicking Open in a separate tab.

    Agent Terminal Window
  • Performance Monitor now shows absolute values of the consumed/total agent memory.

  • You can now switch Build Log timestamps from absolute values to relative to quickly analyze how long it took the build to reach a specific stage.

    Relative timestamps
  • You can now view and copy connection IDs from the Connection pages in TeamCity UI. This minor enhancement facilitates writing Kotlin DSL code for objects that utilize connections: AWS Credentials features, Docker Support, S3 artifact storages, AWS connections that use other connections, and so on.

    Copy connection ID
  • Cloud images' Build History tab now displays a search box that allows you to find all builds of a specific cloud agent, even if this instance is no longer available.

    History for deleted agent
  • The navigation bar now paints the changes indicator bold for favorite projects with changes from the current TeamCity user.

    Highlighted projects with current user changes


  • The DslContext object now exposes a string serverUrl property that allows you to get the URL of a TeamCity server in Kotlin DSL code.

  • TeamCity distributes agents more effectively and processes large build chains with failing builds faster. Starting with version 2023.11, dependent builds whose "On failed dependency" condition is "Make build failed to start" no longer wait for an available agent when their dependencies fail or are canceled. Instead, the dependent build's status changes to "Failed to start" as soon as possible, and TeamCity proceeds to the next build in the chain.

  • The Commit Status Publisher build feature now correctly publishes build statuses for configurations that target refs/(merge-requests/*)/head branches of GitLab repositories (the "merge result" branches). Previously, running TeamCity builds for merge result revisions caused the Publisher to encounter HTTP 404 errors.

  • If users log into TeamCity using credentials of an external 2FA-protected service, TeamCity does not send additional 2FA requests. Learn more: Reduce Excessive Authorization Requests.

  • You can now add the dateFormat=<value> parameter to URLs used by your log analysis tools to retrieve build logs. Learn more: Modify the DateTime Pattern.

  • In addition to builds_queued, builds_started, builds_running and builds_queued metrics, TeamCity now reports an experimental builds_detached metric that allows you to view the number of builds detached from their agents.

Upgrade Notes

Before upgrading, we highly recommend reading about important changes in version 2023.11 compared to 2023.05.

Fixed Issues

See the TeamCity 2023.11 release notes article for the summary of implemented features and fixed issues.


See the TeamCity roadmap to learn about future updates.

Your Feedback Matters

We place a high value on your feedback and encourage you to share your thoughts and suggestions. See this link for more information: Feedback.

Last modified: 21 May 2024