Build Parameters such as configuration parameters, system properties and environment variables, 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 provide a way to override some settings in a build configuration inherited from a 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:
- 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 properties.
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
- env.* variables defined in the Build Configuration.
- env.* variables redefined in the Run Custom Build dialog.
- pre-defined environment variables.
- env.* variables from
System properties passed to the script engine include:
- system.* properties defined in the agent's
- system.* properties defined in the Build Configuration
- system.* properties redefined in the Run Custom Build dialog
- pre-defined system properties
- system.* properties that came from
For details on defining and using parameters, refer to: Defining and Using Build Parameters in Build Configuration, Project and Agent Level Build Parameters.