List of Predefined Build Parameters

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

Predefined build parameters can come from several scopes:

Server build parameters are generated on the server side in the scope of a particular build. For example, a build number.
Agent build parameters are provided on the agent side in the scope of a particular build right before the build start. For example, a path to a file which contains a list of build's changes.
Agent environment parameters are provided by an agent on connection to the TeamCity server. They are not specific to any build and characterize the agent environment (for example, the path to the .NET framework). These are mainly used in agent requirements.

All these parameters are passed to a build.

There is also a special type of server-side build parameters that can be referenced by other parameters but that are not passed to a build directly. See the list of such parameters.

Predefined Server Build Parameters

Here is the list of server build parameters (system properties) predefined in TeamCity and the respective environment variables.

System Property	Environment variable	Description
`teamcity.version`	`TEAMCITY_VERSION`	The version of the TeamCity server. This property can be used to determine if the build is run within TeamCity.
`teamcity.projectName`	`TEAMCITY_PROJECT_NAME`	The name of the project the current build belongs to.
`teamcity.buildConfName`	`TEAMCITY_BUILDCONF_NAME`	The name of the build configuration the current build belongs to.
`teamcity.buildType.id`	none	The unique ID used by TeamCity to reference the build configuration the current build belongs to.
`teamcity.configuration.properties.file`	none	The full name (including the path) of the file containing all the build parameters in alphabetical order.
`build.is.personal`	`BUILD_IS_PERSONAL`	Is set to `true` if the build is personal. Is not defined otherwise.
`build.number`	`BUILD_NUMBER`	The build number assigned to the build by TeamCity. The parameter uses the special build number format.
`teamcity.build.id`	none	The internal unique ID used by TeamCity to reference builds.
`teamcity.auth.userId`	none	A generated username that can be used to download artifacts of other build configurations. Valid only during the build. (Read more details).
`teamcity.auth.password`	none	A generated password that can be used to download artifacts of other build configurations. Valid only during the build. (Read more details).
`build.vcs.number.<VCS_root_ID>`	`BUILD_VCS_NUMBER_<VCS_root_ID>`	The latest VCS revision included in the build for the specified root. See this article for the `<VCS_root_ID>` description. If there is one root in a build configuration, the `build.vcs.number` parameter (without the VCS root ID) is also provided. Note that this value is a VCS-specific (for example, for SVN it is a revision number and for CVS it is a timestamp).

Predefined Agent Build Parameters

Agent build parameters (system properties) are unique for each build. They are calculated on the agent right before the build start and then passed to the build.

System Property	Environment Variable	Description
`teamcity.build.checkoutDir`	none	The checkout directory used for the build.
`teamcity.build.workingDir`	none	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.
`teamcity.build.tempDir`	none	A full path of the build temp directory generated by TeamCity. The directory is cleaned after the build.
`teamcity.build.properties.file`	`TEAMCITY_BUILD_PROPERTIES_FILE`	A full name (including the path) of the file containing all the `system.*` properties passed to the build. The `system.` prefix is omitted. The file uses the Java properties file format (for example, special characters are backslash-escaped).
`teamcity.build.changedFiles.file`	none	A full path to the file with information about changed files included in the build. This property could be useful if you want to support risk test reordering in your custom runner for tests. This file is only available if there were changes in the build. It is not available for history builds.

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 installed applications. TeamCity can automatically detect applications like .NET Framework or Visual Studio and add the corresponding system properties and environment variables.

If additional applications/libraries are available in the environment, the system administrator can manually define the respective parameters manually, in the <Agent Home>/conf/buildAgent.properties file.

These parameters can be used for setting build configuration options, defining build configuration requirements (for example, check if a certain parameter exists), and inside build scripts. For more information on how to reference these properties, see this section.

Here is the list of agent environment parameters predefined in TeamCity:

Agent Parameter	Description
`teamcity.agent.name`	The name of the agent as specified in the `buildAgent.properties` agent configuration file. It can be used to set a requirement for a build configuration to run or not run on a particular build agent.
`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.tools.dir`	The path to the Tools directory on the agent.
`teamcity.agent.jvm.os.version`	The corresponding JVM property.
`teamcity.agent.jvm.user.country`	The corresponding JVM property.
`teamcity.agent.jvm.user.home`	The corresponding JVM property.
`teamcity.agent.jvm.user.timezone`	The corresponding JVM property.
`teamcity.agent.jvm.user.name`	The corresponding JVM property).
`teamcity.agent.jvm.user.language`	The corresponding JVM property.
`teamcity.agent.jvm.user.variant`	The corresponding JVM property.
`teamcity.agent.jvm.file.encoding`	The corresponding JVM property.
`teamcity.agent.jvm.file.separator`	The corresponding JVM property.
`teamcity.agent.jvm.path.separator`	The corresponding JVM property.
`teamcity.agent.jvm.specification`	The corresponding JVM property.
`teamcity.agent.jvm.version`	The corresponding JVM property.
`teamcity.agent.jvm.java.home`	See the section below for details.
`teamcity.agent.os.arch.bits`	The agent's OS bitness.
`DotNetFramework<version>[_x86\|_x64]`	This parameter is defined 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 have 3.5, 4.5, and 4.8 versions installed, this parameter will only be defined for 3.5 and 4.8. 4.5 will be omitted as there is a later available version of .NET Framework 4. To explicitly define such a version, consider using the `DotNetFrameworkTargetingPack<version>_Path` parameter instead.
`DotNetFrameworkSDK<version>[_x86\|_x64]`	This parameter is defined if the corresponding version(s) of .NET Framework SDK is installed.
`DotNetFrameworkSDK<version>[_x86\|_x64]_Path`	The path of the corresponding framework SDK version.
`DotNetFrameworkTargetingPack<version>_Path`	The path to the corresponding Reference assemblies (AKA Targeting Pack) location.
`WindowsSDK<version>`	This property is defined if the corresponding version of Windows SDK is installed.
`WindowsSDK<version>_Path`	This property value is the path of the corresponding version of Windows SDK.
`VS[2003\|2008\|2013\|2017]`	This property is defined if the corresponding version(s) of Visual Studio is installed
`VS[2003\|2008\|2013\|2017]_Path`	The path to 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 processors in the build agent system.
`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.
The agent tools directory, <Agent Home Directory>/tools, is checked for containing a JRE or JDK. By default, the subdirectories of /tools are not scanned. To search the subdirectories, define teamcity.agent.java.search.path=%agent.tools.NAME%/INNER_PATH in the buildAgent.properties file.
For Unix and macOS, remember to set the executable bit on the files for TeamCity to be able to launch the discovered Java.
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 get the full list of such server parameters, add the system.teamcity.debug.dump.parameters parameter to a build configuration and then view the "Available server properties" section in the build log.

Dependency Parameters

These configuration parameters are provided by the builds the current build depends on (via a snapshot or artifact dependency).

In a dependent build, that is later in the chain, dependency parameters of the previous builds have the following format:

dep.<btID>.<parameter_name>

<btID> — the ID of a dependency build configuration to get the parameter from. Indirect dependency configurations are also available (for example, A depends on B and B depends on C — A will be able to access the parameters of C).
<parameter_name> — the name of the build parameter.

If there are multiple dep.<btID>.<parameter_name> paths to the same build configuration with btID, so that different builds are accessible via (direct or indirect) artifact dependencies, the following rules apply:

If there is a snapshot dependency between some of the builds, the build from the same chain wins.
If there are no snapshot dependencies and multiple builds are accessible only via an artifact dependency, the build with a larger build ID wins. If there are several artifact dependencies from a single build configuration, only the first one is considered.

Overriding Dependency Parameters

It is possible to override values of build parameters of the snapshot-dependency builds in the current build, on its start.

For example, build configuration A depends on B and B depends on C.

On triggering, A can change any parameter used in B or C by setting the following parameter:

reverse.dep.<btID>.<parameter_name>

<parameter_name> is the name of the parameter to set in the build configuration <btID>. To set a system property, include the system. prefix in <parameter_name>.

To change a parameter in all dependency builds at once, use a wildcard:

reverse.dep.*.<parameter_name>

If several dependency build configurations have alike IDs, that is their beginning and/or ending match, you can apply a filter and change a build parameter only in these dependencies. Use the following syntax:

reverse.dep.[prefix]*[suffix].<parameter_name>

where prefix corresponds to the beginning of the target builds' IDs, and suffix corresponds to their ending. Both attributes are optional. Only one * symbol is allowed.

Each dependent build in a chain can redefine parameters in any of its dependency builds.

If build configurations A and B are trying to set different values for the same parameter in the build configuration C, the following rules apply:

If A depends on B by a snapshot dependency either directly or transitively, the value proposed by A will be used in C.
If both A and B do not depend on each other, TeamCity will consider it a conflict and will not modify the original value in C. Instead, two other parameters will be created for C:
- conflict.<btA>.<parameter_name>=<valueA>
- conflict.<btB>.<parameter_name>=<valueB>
The priority of a reverse parameter's value depends on the way it is defined:
- Top priority: if a value is redefined in the specific build via <btID>.
- Medium priority: if a value is redefined in a set of builds via [prefix]*[suffix]. Among them, the longer values are considered more specific and thus have higher priority than the shorter ones.
- Low priority: if a value is redefined in all preceding builds via *.

The reverse.dep.* parameters are processed on queuing the build where these parameters are defined. As the parameters' values should be known at that stage, they should be defined only either as build configuration parameters or in the custom build dialog. Setting the parameter during the build steps has no effect.

Note that the values of the reverse.dep. parameters are pushed to the dependency builds "as is", without reference resolution. %-references, if any, will be resolved in the context of the build where the parameters are pushed to.

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

Parameter	Description
`teamcity.build.triggeredBy`	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: 26 April 2022