List of Predefined Build Parameters

TeamCity provides dozens of predefined build parameters ready to be used in the settings of a build configuration or in build scripts.

All these parameters (except Predefined Configuration Parameters) are passed to a build process. Note that the techniques required to access these parameters may vary depending on your build type (for example, see the Build Properties section for the information on accessing TeamCity system properties in Gradle builds).

Predefined Server Build Parameters

These parameters are generated on the server side in the scope of a particular build — for example, a build number.

Server build parameters are typically available as a system property and a corresponding environment variable.

system.teamcity.version | env.TEAMCITY_VERSION: The version of the TeamCity server. This property can be used to determine if the build runs within TeamCity.
system.teamcity.projectName | env.TEAMCITY_PROJECT_NAME: The name of the project the current build belongs to.
system.teamcity.buildConfName | env.TEAMCITY_BUILDCONF_NAME: The name of the build configuration the current build belongs to.
system.teamcity.buildType.id: The unique ID used by TeamCity to reference the build configuration the current build belongs to.
system.teamcity.configuration.properties.file: The full name (including the path) of the file that contains all the build parameters in alphabetical order. This file is written when a build process starts and uses the Java Properties File format (for example, special characters are backslash-escaped). See also: build.properties.file
system.build.is.personal | env.BUILD_IS_PERSONAL: Returns true for personal builds. Undefined (does not exist) for regular builds.
system.build.number | env.BUILD_NUMBER: The build number assigned to the build by TeamCity. The parameter uses the special build number format.
env.BUILD_URL: The link to the current build.
system.teamcity.build.id: The internal unique ID used by TeamCity to reference builds.
system.teamcity.auth.userId: A generated username that can be used to download artifacts of other build configurations. Valid only during the build. See this section for more information: Build-level Authentication.
system.teamcity.auth.password: A generated password that can be used to download artifacts of other build configurations. Valid only during the build. See this section for more information: Build-level Authentication.
system.build.vcs.number.<VCS_root_ID> | env.BUILD_VCS_NUMBER_<VCS_root_ID>: The latest VCS revision included in the build for the specified root. See the following article for more information about VCS root IDs: Configuring VCS Roots.

If a build configuration has only one VCS root, you can use the build.vcs.number parameter without the root ID identifier.

This value is a VCS-specific. For example, a revision number for SVN and a timestamp for CVS.

Predefined Agent Build Parameters

These system properties are unique for each build (for example, a path to a file that contains a list of changes). Their values are calculated on the agent side right before the build starts and then passed to the build.

system.teamcity.build.checkoutDir: The checkout directory used for the build.
system.teamcity.build.workingDir: The working directory where the build is started. This is the path where a TeamCity build runner is supposed to start a process. This is a runner-specific property, thus it has a different value for each step.
system.teamcity.build.tempDir: A full path of the build temp directory generated by TeamCity. The directory is cleaned after the build.
system.teamcity.build.changedFiles.file: A full path to the file with information about changed files included in the build. You can use this property to support risk test reordering in your custom runner for tests.

This file is not available for history builds and if there were no changes in this particular build.
system.teamcity.build.properties.file | env.TEAMCITY_BUILD_PROPERTIES_FILE: The full name (including the path) of the file containing all build system properties without their system. postfix. This file is written when a build process starts and uses the Java Properties File format (for example, special characters are backslash-escaped).

Predefined Agent Environment Parameters

These agent-specific parameters are defined on each build agent and vary depending on its environment. Aside from standard parameters (for example, teamcity.agent.jvm.os.name or teamcity.agent.jvm.os.arch provided by the JVM running on an agent), agents can have parameters based on their installed software. TeamCity automatically detects software like .NET Framework, Mono, or Visual Studio and adds the corresponding system properties and environment variables.

If an agent machine has additional software installed, system administrators can modify the <Agent Home>/conf/buildAgent.properties file to override values of corresponding parameters.

Agent environment parameters can be used to set build configuration options, define agent requirements, and inside build scripts.

To check all existing parameters and their current values for a given build agent, open the agent details page and switch to the Parameters tab. See this link for more information: Checking Parameter Values.

teamcity.agent.name: The agent's name. You can use agent names to specify agent requirements and limit the number of agents a target configuration can use.
teamcity.agent.work.dir: The path to the agent work directory.
teamcity.agent.work.dir.freeSpaceMb: Free space available in the agent work directory.
teamcity.agent.home.dir: The path to the agent home directory
teamcity.agent.jvm.os.version: The operating system version. Reports a value of the corresponding JVM property.
teamcity.agent.jvm.user.country: The user country. Reports a value of the corresponding JVM property.
teamcity.agent.jvm.user.home: The user's home directory. Reports a value of the corresponding JVM property.
teamcity.agent.jvm.user.timezone: The user's timezone. Reports a value of the corresponding JVM property.
teamcity.agent.jvm.user.name: The user's account name. Reports a value of the corresponding JVM property.
teamcity.agent.jvm.user.language: The user's primary OS language. Reports a value of the corresponding JVM property.
teamcity.agent.jvm.user.variant: An arbitrary value used to indicate a variation of a user locale. Reports a value of the corresponding JVM property.
teamcity.agent.jvm.file.encoding: The name of the default charset, defaults to UTF-8. Reports a value of the corresponding JVM property.
teamcity.agent.jvm.file.separator: The file separator. Reports a value of the corresponding JVM property.
teamcity.agent.jvm.path.separator: The path separator. Reports a value of the corresponding JVM property.
teamcity.agent.jvm.specification: Java Runtime Environment specification version. Return the value of the java.specification.version JVM property.
teamcity.agent.jvm.version: Java Virtual Machine implementation version. Reports a value of the corresponding JVM property.
teamcity.agent.jvm.java.home: Java installation directory. See the following section for more information: Java-Related Environment Variables.
teamcity.agent.os.arch.bits: The agent's OS bitness.
DotNetCLI: The .NET CLI version.
DotNetCLI_Path: The path to .NET CLI executable.
DotNetFramework<version>[_x86|_x64]: Defined only if the corresponding version(s) of .NET Framework runtime is installed.
DotNetFramework<version>[_x86|_x64]_Path: This parameter's value is set to the corresponding framework runtime version(s) path(s).

Note that this parameter is defined only for the latest installed version per major release. For example, if you installed versions 3.5, 4.5, and 4.8, this parameter will only be defined for 3.5 and 4.8. Version/Parameter 4.5 will be omitted since a newer version of .NET Framework 4 is present. To explicitly define such a version, consider using the DotNetFrameworkTargetingPack<version>_Path parameter instead.
DotNetFrameworkSDK<version>[_x86|_x64]: Defined if the corresponding version(s) of .NET Framework SDK is installed.
DotNetFrameworkSDK<version>[_x86|_x64]_Path: The path to the corresponding framework SDK version.
DotNetFrameworkTargetingPack<version>_Path: The path to the corresponding Reference assemblies (AKA Targeting Pack) location.
DotNetCoreSDKx.x_Path: The .NET SDK version.
DotNetWorkloads_<version>: Lists all .NET workloads installed on the agent machine.

The <version> suffix is the version of an installed .NET SDK. For instance, if version 7.0.300 is installed, the agent will report the `DotNetWorkloads_7.0.300` parameter.

In addition to these full SDK versions, agents report workload parameters with shortened major.minor suffixes. For example, if an agent machine has 7.0.100, 7.0.200, and 7.0.300 .NET SDKs installed, the DotNetWorkloads_7.0 parameter that refers to the highest 7.0.300 version will be reported.

The parameter value is a string of comma-separated workload names, according to folders in the <dotnet_dir>/metadata/workloads/<sdk_version>/InstalledWorkloads directory. For instance, "android,maui-ios,wasm-tools".
WindowsSDK<version>: Defined only if the corresponding version of Windows SDK is installed.
WindowsSDK<version>_Path: The path of the corresponding version of Windows SDK.
VS<Version>: Defined if the corresponding version(s) of Visual Studio is installed
VS<Version>_Path: The path to the Visual Studio installation folder (the directory that contains devenv.exe).
teamcity.dotnet.nunitlauncher<version>: The path to the directory that contains the standalone NUnit test launcher, NUnitLauncher.exe. The version number refers to the version of .NET Framework under which the test will run. The version equals the version of .NET Framework.
teamcity.dotnet.nunitlauncher.msbuild.task: The path to the directory that contains the MSBuild task dll providing the NUnit task for MSBuild, Visual Studio (sln).
teamcity.dotnet.msbuild.extensions2.0: The path to the directory that contains MSBuild 2.0 listener and tasks assemblies.
teamcity.dotnet.msbuild.extensions4.0: The path to the directory that contains MSBuild 4.0 listener and tasks assemblies.
teamcity.agent.ownPort: The agent port used by the TeamCity server to connect to the agent.
teamcity.agent.protocol: The protocol used for data transfers between the agent and the server.
teamcity.agent.cpuBenchmark: The CPU benchmarking result for the agent.
teamcity.agent.hardware.cpuCount: The number of cores/threads on the agent machine's CPU.
teamcity.agent.hostname: The name of the build agent host.

When a build agent starts, it detects the installed JDK and JRE and then defines Java-related environment variables as described below. If a started agent already has the Java-related environment variables set, they are not redefined.

These variables can be used in build scripts as usual environment variables.

Detecting Java on Agent

An agent searches and launches all Java installations to verify they are valid. It determines the Java version and bitness based on the output.

The following locations are searched (some locations are common for all OSs, some are OS-specific):

A custom directory on the agent, if defined. See how to define a custom directory.
In the paths specified by the JAVA_HOME, JDK_HOME, JRE_HOME environment variables, if defined.
The OS-specific locations:
- The Windows Registry is searched for the Java installed with the Java installer.
- The C:\Program Files and C:\Program Files (x86) directories are searched for Java and JavaSoft subdirectories.
- C:\Java
- /usr/local/java
- /usr/local
- /usr/java
- /usr/lib/jvm
- /usr
- /System/Library/Frameworks/JavaVM.framework/Versions/<Java Version>/Home
- /Library/Java/JavaVirtualMachines/Versions/<Java Version>/Home
- /Library/Java/JavaVirtualMachines/<Java Version>/Contents/Home
In the path specified by the PATH environment variable, if defined.

Defining Custom Directory to Search for Java

You can define a custom directory on an agent to search for Java installations. To do this, add the teamcity.agent.java.search.path property to the buildAgent.properties file.

You can define a list of directories: the type of separator character depends on the OS.

For each version of Java, the following variable is defined: JDK_<major>_<minor>[_x64]. For example, env.JDK_1_6 (Java 6) or env.JDK_14_0_x64 (Java 14 64-bit).

The JDK variables are defined when the JDK is found. Before Java 11, the JRE variables are defined when the JRE is found but the JDK is not.
The _x64 variables point to 64-bit Java only. The variables without the _x64 suffix may point to both 32-bit or 64-bit installations but 32-bit ones are preferred.
If several installations with the same major version and the same bitness, but different minor version/update are found, the latest one is selected.

In addition, the following variables are defined:

JAVA_HOME — for the latest JDK installation (but 32-bit one is preferred).
JDK_HOME — the same as JAVA_HOME.
JRE_HOME — for the latest JRE or JDK installation (but 32-bit one is preferred), defined even if JDK is found.

The JRE_HOME and JDK_HOME variables may point to different installations. For example, if JRE 1.7 and JDK 1.6 but no JDK 1.7 installed — JRE_HOME will point to JRE 1.7 and JDK_HOME will point to JDK 1.6.

All variables point to the Java Home directories, not to binary files. For example, if you want to execute javac version 1.6, you can use the following path:

%env.JDK_1_6%/bin/javac

%JDK_1_6%\bin\javac

$JDK_1_6/bin/javac

Predefined Configuration Parameters

Configuration parameters can be referenced by other parameters (only if defined on the Parameters page), but they are not passed to the build.

To view the complete list of these server parameters, open the Parameters tab of any build or download the internal teamcity/properties/build.start.properties.gz artifact.

Dependency Parameters

See the following article to learn more about dependency parameters: Use Parameters in Build Chains.

VCS Parameters

These are the settings of VCS roots attached to a build configuration.

VCS parameters have the following format:

vcsroot.<VCS_root_ID>.<VCS_root_parameter_name>

<VCS_root_ID> — the VCS root ID.
<VCS_root_parameter_name> — the name of the VCS root parameter. This parameter is VCS-specific. See how to get the available list of parameters.

If there is only one VCS root in a build configuration, the <VCS_root_ID>. part can be omitted.

Parameters marked by the VCS as secure (for example, passwords) are not available for referencing.

Build Branch Parameters

When TeamCity starts a build in a build configuration where a branch specification is configured, it adds a branch label, or logical name, to each build. This logical name is also available as a configuration parameter:

teamcity.build.branch

To distinguish builds started on a default and a non-default branch, there is an additional boolean configuration parameter which allows differentiating these cases:

teamcity.build.branch.is_default=true|false

For Git and Mercurial, TeamCity provides additional parameters with the names of VCS branches known at the moment of the build start. Note that these may differ from the logical branch name as per branch specification configured. This VCS branch is available from a configuration parameter with the following name:

teamcity.build.vcs.branch.<VCS_root_ID>

where <VCS_root_ID> is the VCS root ID.

Other Parameters

teamcity.build.triggeredBy: Returns the human-friendly description of how the build was triggered.
teamcity.build.triggeredBy.username: If the build was triggered by a user, the username of this user is reported. When a build is triggered not by a user, this property is not reported.

Last modified: 29 May 2024