Parameters that can be defined in TeamCity are of two types:
- Configuration parameters are never passed to a build and serve as a way to make build configuration's settings more flexible.
- Build parameters include system properties and environment variables which are sent to a build runner, when a build is started.
Hereinafter system properties and environment variables are referred to as build parameters, when both types are meant.
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 be means of configuration parameters. Please, refer to the Build Configuration Template page for the list of settings that can be redefined be 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 Properties and Environment Variables 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 Properties and Environment Variables 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.
Build parameters include system properties and environment variables. They 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.
Build parameters are name-value pairs that can be defined by the project administrator or provided by TeamCity as predefined properties.
Where Build Parameters Are Defined
There are several places where you can define build parameters:
- Properties and environment variables 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