Predefined Build Parameters

TeamCity provides a number of Configuring Build Parameters which are ready to be used in the settings of a build configuration or in build scripts.

The predefined build parameters can originate from several scopes:

• Server-Build-Properties - the parameters generated by TeamCity on the server-side in the scope of a particular build. An example of such property is a build number.

• Agent-Properties - the parameters provided by an agent on connection to the server. The parameters are not specific to any build and characterize the agent environment (for example, the path to .Net framework). These are mainly used in Agent Requirements.

• Agent-Build-Properties - the parameters provided on the agent side in the scope of a particular build right before the build start. For example, a path to a file with a list of changed files.

All these parameters are finally passed to the build.

There is also a special kind of server-side build parameters that can be used in references while defining other parameters, but which are not passed into the build. See Configuration-Parameters below for the list of such properties.

Server Build Properties

Configuration Parameters

These are the parameters that other properties can reference (only if defined on the Build Parameters page), but that are not passed to the build themselves. You can get the full set of such server properties by adding the system.teamcity.debug.dump.parameters property to a build configuration and examining the "Available server properties" section in the build log.

Among these properties are the following:

Dependencies Properties

These are properties provided by the builds the current build depends on (via a snapshot or an artifact Dependent Build).

Dependencies properties have the following format:

dep.<btID>.<property name>

• <btID> — is the Configuring General Settings of the build configuration to get the property from. Only the configurations the current one has snapshot or artifact dependencies on are supported. Indirect dependencies configurations are also available (e.g. A depends on B and B depends on C - A will have C's properties available).

• <property name> — the name of the Server-Build-Properties of the build configuration with the given ID.

VCS Properties

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

VCS properties have the following format:

vcsroot.<VCS root ID>.<VCS root property name>

• <VCS root ID> — is the VCS root ID as described on the Configuring VCS Roots page.

• <VCS root property name> — the name of the VCS root property. This is VCS-specific and depends on the VCS support. You can get the available list of properties as described get_listing_of__reference_only_properties.

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

Properties marked by the VCS support as secure (for example, passwords) are not available as reference properties.

Branch-Related Parameters

When TeamCity starts a build in a build configuration where Working with Feature Branches is configured, it adds a branch label to each build. This logical branch 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 available since 7.1.5 which allows differentiating these cases:

teamcity.build.branch.is_default=true|false

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

teamcity.build.vcs.branch.<VCS root ID>

Where <VCS root ID> is the VCS root ID as described on the Configuring VCS Roots page.

Other Parameters

Agent Properties

Agent-specific properties are defined on each build agent and vary depending on its environment. Aside from standard properties (for example, teamcity.agent.jvm.os.name or teamcity.agent.jvm.os.arch, etc. — these are provided by the JVM running on agent) agents also have properties based on installed applications. TeamCity automatically detects a number of applications including the presence of .NET Framework, Visual Studio and adds the corresponding system properties and environment variables. A complete list of predefined agent-specific properties is provided in tablePredefinedProperties below.

If additional applications/libraries are available in the environment, the administrator can manually define the property in the <agent home>/conf/buildAgent.properties file. These properties can be used for setting various build configuration options, for defining build configuration requirements (for example, existence or absence of some property) and inside build scripts. For more information on how to reference these properties, see the Defining and Using Build Parameters in Build Configuration page.

In the TeamCity Web UI, the actual properties defined on the agent can be reviewed by going to the Agents tab at the top navigation bar|<Agent>|<Agent> page|the Agent Parameters tab:

Agent Environment Variables

An agent can define some environment variables. These variables can be used in build scripts as usual environment variables.

Java Home Directories

When a build agent starts, first the installed JDK and JRE are detected; when they are found, the Java-related environment variables are defined as described in Setting-Java-related-Environment-Variables.

Detecting Java on Agent

The installed Java is searched for in the ALL locations listed below. Then, every discovered Java is launched to verify that it is a valid Java installation, and the Java version and bitness are determined based on the output.

The following locations are searched (a number of locations is common for all operating systems; some of them are OS-specific):

• It is checked whether the JAVA_HOME, JDK_HOME, JRE_HOME variables are defined

• The PATH environment variables are searched and the discovered directories are checked for containing Java

• If defined, a custom directory on an agent is searched for Java installations. Defining a custom directory to search for Java is described Defining-Custom-directory-to-Search-for-Java.

Windows

• The Windows Registry is searched for the Java installed with the Java installer

• C:\Program Files and C:\Program Files (x86) directories are searched for Java and JavaSoft subdirectories

• the C:\Java directory is searched

Unix

The following directories are searched for for Java subdirectories:

• /usr/local/java

• "/usr/local

• /usr/java

• /usr/lib/jvm

• /usr

Mac OS The following directories are searched:

• /System/Library/Frameworks/JavaVM.framework/Versions/<Java Version>/Home

• /Library/Java/JavaVirtualMachine/Versions/<Java Version>/Home

• /Library/Java/Jcd cdavaVirtualMachine/<Java Version>/Contents/Home

Defining Custom directory to Search for Java

You can define a custom directory on an agent to search for Java installations in by adding the teamcity.agent.java.search.path property to the Build Agent Configuration file.

You can define a list of directories separated by an OS-dependent character.

Defining Java-related Environment Variables

For each major version V of java, the following variables can be defined:

• JDK_1 V

• JDK_1 V _x64

• JRE_1 V

• JRE_1 V _x64

The JDK variables are defined when the JDK found, the JRE variables are defined when the JRE found but the JDK is not found. The _x64 variables point to 64-bit java only; the variables without the _x64 suffix may points 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 additional, 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 points 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:

In a TeamCity build configuration:

%env.JDK_16%/bin/javac

In a Windows bat/cmd file:

%JDK_16%\bin\javac

In a unix shell script:

$JDK_16/bin/javac

Agent Build Properties

These properties are unique for each build: they are calculated on the agent right before build start and are then passed to the build.