Configuring Build Parameters

Types of Build Parameters

Build parameters are name-value pairs, defined by a user or provided by TeamCity, which can be used in a build. There are three types of build parameters:

• Environment variables

• System properties

• Configuration parameters

Levels of Parameters

The parameters can be defined at different levels (in order of precedence):

• a specific build (via the Run Custom Build dialog)

• the Parameters page of Build Configuration Settings or Build Configuration Template

• the Parameters page of Project Settings; these affect all the build configurations and templates of the project and its subprojects

• a build agent (the <Agent home>/conf/buildAgent.properties file on the agent)

Parameter Name Restrictions

The name of a configuration parameter must satisfy the following requirements:

• contain only the following characters: [a-zA-Z0-9._-*]

• start with an ASCII letter

Parameter References

Any textual setting can reference a parameter. A string in the %parameter.name% format will be substituted with the actual value during the build. If a build references a parameter which is not defined, TeamCity considers it an implicit agent requirement: the build will only run on the agents with this parameter defined.

The references to parameters which names do not satisfy the above restrictions do not create an implicit requirement.

Predefined and Custom Parameters

TeamCity provides a set of predefined parameters. Administrators can add custom parameters, as described below.

%[env|system].property_name%
For example: system.tomcat.libs=%env.CATALINA_HOME%/lib/*.jar

Using Build Parameters in Build Configuration Settings

In most build configuration settings, you can use a reference to a build parameter instead of using the actual value. Before starting a build, TeamCity resolves all references with the available parameters. If there are references that cannot be resolved, they are left as is; a respective warning appears in the build log.

To reference a build parameter, use its name enclosed in percentage signs: for example, %teamcity.build.number%.

TeamCity considers a reference to a property any text that is enclosed in percentage symbols. If the property cannot be found in the build configuration, the reference becomes an implicit agent requirement and such build configuration can only be run on an agent with this property defined. The agent-defined value will be used in the build.
If you want to prevent TeamCity from treating the text in the percentage signs as a reference to a property, use two percentage signs. Every occurrence of %% in the values where property references are supported will be replaced with % before passing the value to the build. For example, if you want to pass %Y%m%d%H%M%S into the build, change it to %%Y%%m%%d%%H%%M%%S.

Using Build Parameters in VCS Labeling Pattern and Build Number

In the build number pattern and VCS labeling pattern, you can use the %[env|system].property_name% syntax to reference the properties that are known on the server side:

• server and reference predefined properties;

• properties defined on the Build Configuration Settings | Parameters page.

For example, a VCS revision number can be specified as %build.vcs.number%.

Using Build Parameters in Build Scripts

All build parameters starting with the env. prefix (environment variables) are passed into the build's process environment (omitting the prefix).

All build parameters starting with system. prefix (system properties) are passed to the supported build script engines and can be referenced there by the property name, without the system. prefix. You can this prefix to access these properties in the TeamCity UI or, for example, in the Command Line runner.
Note that this syntax will work in the build script (not in TeamCity settings):

• For Ant, Maven, and NAnt, use ${<property name>}.

• For .NET, use $(<property name>). Note that MSBuild does not support names with dots (.), so you need to replace . with _ when using the property inside a build script. Note that the nuget push and nuget delete commands do not support properties.

• For Gradle, the TeamCity system properties can be accessed as Gradle properties (similar to the ones defined in the gradle.properties file) and are to be referenced as follows:

  • name allowed as a Groovy identifier (the property name does not contain dots):

  println "Custom user property value is $\{customUserProperty\}"

  • name not allowed as a Groovy identifier (the property name contains dots: for example, build.vcs.number.1): project.ext["build.vcs.number.1"]

note

Using the teamcity["<property_name>"] syntax is not recommended, although still supported.

When TeamCity starts a build process, the following precedence of the build parameters is used (those on top have higher priority):

• parameters from the project- and agent-level build parameters file

• predefined parameters

• parameters defined in the Run Custom Build dialog

• parameters defined in build configuration settings

• parameters defined in a project (the parameters defined for a project will be inherited by all its subprojects and build configurations; if required, you can redefine them in a build configuration)

• parameters defined in a template (if any)

• parameters defined in the agent's buildAgent.properties file

• environment variables of the build agent process itself

The resultant set of parameters is also saved into a file which can be accessed by the build script. See the teamcity.build.properties.file system property or TEAMCITY_BUILD_PROPERTIES_FILE environment variable description in Predefined Build Parameters for details.