Configuring Build Parameters

Build Parameters such as ConfigurationParameters, BuildParameters, provide you with flexible means of sharing settings within a single Build Configuration, managing compatible agents based on specific environment (see Configuring Agent Requirements) and a convenient way of passing generic or environment-specific settings into the build script. In this section:

Configuration Parameters

Configuration parameters provide a way to override some settings in a build configuration inherited from a Build Configuration Template. They are never passed to a build. As a rule, a build configuration created based on a template inherits all the settings defined in the template. You cannot edit these settings for the particular build configuration, whereas modifying them in the template will influence all configurations associated with this template. However, you can bypass this behavior by means of configuration parameters. Please, refer to the Build Configuration Template to see which settings can be redefined by means of configuration parameters.

Using references to configuration parameters

To introduce a configuration parameter use %\ParameterName% syntax in the template text fields thus providing means to change actual values of such parameters in associated build configuration. Once introduced, such parameter appears on the Build Parameters page of the build configuration template with undefined value.

You can either specify parameter's default value or leave it without any value.

Example of configuration parameters usage

Assume that you have two similar build configurations that differ only by checkout rules. For instance, checkout rules for the first configuration should contain ' :release_1_0 => .', and for the second ':trunk => .'. All other settings are equal. It would be useful to have one template to associate with both build configurations, but with means to change checkout rules in each build configuration separately.

To do so, perform the following steps:

Extract template from either of those configurations.
In template settings navigate to Version Control Settings, open Checkout rules dialog and enter there: %\checkout.rules%
For inherited build configuration, open configuration settings page and on the Build Parameters page specify the actual value for the checkout.rules configuration parameter.
For the second build configuration click on the "Associate with template" button and choose the template. Specify appropriate value for checkout.rules parameter right in the "Associate with Template" dialog. Click "Associate".

As a result, you'll have two build configurations with different checkout rules, but associated with one template.

This way you can create a configuration parameter and then reference it from any build configuration, which has a text field.

System Properties and Environment Variables

System properties and environment variables provide you with a flexible means of sharing settings within a single Build Configuration, managing compatible agents based on specific environment (see Configuring Agent Requirements) and a convenient way of passing generic or environment-specific settings into the build script. System properties and environment variables are name-value pairs that can be defined by the project administrator or provided by TeamCity as Predefined Build Parameters.

Where system properties and environment variables are defined

There are several places where you can define system properties and environment variables:

Build Parameters page of Build Configuration settings.
Run Custom Build dialog, when launching a custom build.
In dedicated teamcity.default.properties file, which should be put in the VCS root.
In Agent Properties, specified in agent's <Agent home>/conf/buildAgent.properties file.

What system properties and environment variables are passed to build process

When TeamCity starts a build process the following set of environment variables is used:

environment variables of the Build Agent process itself.
env.* variables defined in the agent's buildAgent.properties file.
env.* variables defined in the Build Configuration.
env.* variables redefined in the Run Custom Build dialog.
Predefined Build Parameters environment variables.
env.* variables from teamcity.default.properties file.

System properties passed to the script engine include:

system.* properties defined in the agent's buildAgent.properties file
system.* properties defined in the Build Configuration
system.* properties redefined in the Run Custom Build dialog
Predefined Build Parameters system properties
system.* properties that came from teamcity.default.properties file

For details on defining and using parameters, refer to: Defining and Using Build Parameters in Build Configuration, Project and Agent Level Build Parameters.

Last modified: 20 April 2023