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.
- teamcity.build.responsibleNode.id
In multinode setup, this parameter returns the node to which it is attached. Can be assigned to the
X-TeamCity-Node-Id-Cookie
cookie when sending logging REST API requests to the/app/rest/builds/id:build_id/log
endpoint.- 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 name of the agent as specified in the
buildAgent.properties
agent configuration file. 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.tools.dir
The path to the Tools directory on the agent.
- 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, theDotNetWorkloads_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.
Java-Related Environment Variables
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, defineteamcity.agent.java.search.path=%agent.tools.NAME%/INNER_PATH
in thebuildAgent.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
andC:\Program Files (x86)
directories are searched forJava
andJavaSoft
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.
Defining Java-Related Environment Variables
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 asJAVA_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:
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:
<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:
To distinguish builds started on a default and a non-default branch, there is an additional boolean configuration parameter which allows differentiating these cases:
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:
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.