Build Configuration Template

Build configuration templates are intended to eliminate duplicating settings of the build configuration. To save your time you can copy build configuration that seems most suitable, and use it as a base for a new one. However, if any parameter needs modification, you will still have to make same changes in all similar build configurations. With templates, you need to edit template settings only, and the changes will affect all configurations which are associated with this template.

You can create a build configuration template in two ways:

• Create new template manually. This process is similar to creating regular build configuration. For more information, please refer to the Create Edit Build Configuration Template page.

• Extract new template from a build configuration. To do so, navigate to the desired build configuration settings page, click Extract Template and type a name for the new template in appeared dialog window. Please note, that in this case the build configuration, from which the new template was extracted, will be attached automatically to this newly created template.

When a template is created, you can associate with it any number of build configurations. To do so, navigate to the build configuration settings page, click Associate with Template in the side bar, and specify particular template to associate current configuration with.

If a build configuration is associated with a template, then settings of this build configuration are inherited from the template. However, some settings can be redefined; for more details see Changing-Parameters-in-Associated-Configuration section below.

When you detach build configuration from a template, all settings from the template will be copied to the build configuration and enabled for editing.

Template which has at least one associated build configuration cannot be deleted.

Changing Parameters in Associated Configuration

As mentioned above, if a build configuration is associated with a template, then settings of this build configuration are taken from the template by default. However, it is possible to override some settings on the build configuration level:

• You can extend list of settings and change inherited values (inherited settings can't be removed!) for the:

  • Properties & Environment variables.

  • Requirements.

  • Snapshot dependencies.

  • Artifact dependencies. Please note that for artifact dependencies only extension of settings list is available; redefinition is partly allowed via parameter references in text fields.

• The following settings can be Parameter-References:

  • Values for most of the text fields in a build configuration

  • Checkout rules

  • VCS trigger include rules

Currently, re-definition is not available for the following settings:

• VCS roots - the set of VCS roots inherited as is and can't be extended (but checkout rules can be redefined)

• Build runner type can't be changed, however most of the build runner settings can be redefined with help of parameter references

• Build triggers cannot be added/removed.

• Settings represented in the web UI as check-boxes / radio buttons and drop-down lists.

Using Parameter References

TeamCity allows using configuration parameters with %\param.name% syntax in the template text fields thus providing means to change actual values of such parameters in attached configuration itself.

To create new configuration parameter, use 6.Properties and environment variables section of the template settings. When a parameter created, you can reference it in any template's text field.

You can either specify parameter's default value or leave the value blank. If configuration parameter has a default value, then this value will be used in associated build configuration, unless you change it manually in the particular build configuration itself.

Example of Configuration Parameters Usage

The following example shows how the configuration parameters work.

Assume that you have two similar build configurations that differs only in checkout rules. For instance, let's say for the first configuration checkout rules should contain ' :release_1_0 => .', and for the second configuration — ':trunk => .'. It would be useful to have one build template to associate with both configurations. In this case you will need means to change checkout rules in each build configuration itself.

To solve the task, you need to perform the following procedure:

1. Extract template from either of those configurations

2. In template settings navigate to 2.Version Control Settings, open Checkout rules dialog and enter there: %\checkout.rules%

3. For inherited build configuration, open configuration settings page and in the 6.Properties and environment variables page specify the appropriate actual value for the checkout.rules configuration parameter.

4. For the second build configuration click on the "Associate with template" button and choose template. Specify appropriate value for checkout.rules parameter right in the "Associate with Template" dialog. Click "Associate" button.

The task is solved: we have two build configurations associated with one template and individual checkout rules.

In such manner you can create a configuration parameter and then reference it from any build configuration, which has a text field.