Unable to render embedded object: File (TeamCity48.png) not found.

TeamCity 10.x and 2017.x Documentation

Icon

You are viewing the documentation of TeamCity 10.x and 2017.x, which is not the most recently released version of TeamCity.
View this page in the latest documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

 

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Table of Contents

Overview

Build Configuration Templates allow Templates allow you to eliminate duplication of build configuration settings. If you want to have several similar (not necessarily identical) build configurations and be able to modify to modify their common settings in one place without place without having to edit each configuration, create a build configuration template with those settings. Modifying template settings affects all build all build configurations associated with this template. 
   Since TeamCity 2017.2, it is possible to define a default template in a project for all build configurations in this project and its subprojects. See the section below for details. 

Build configuration templates support project hierarchy: once created, available templates include the ones from the current project and its parents. On copying a project or a build configuration, the templates that do not belong to the target project or one of its parents are automatically copied. You can associate a build configuration a template only if the template belongs to the current project or one of its parents.

 

Note

If you upgraded from versions earlier than TeamCity 8.0, your configurations from one project might be associated with templates from an unrelated project. After upgrading to TeamCity 8+, such templates may become inaccessible. To reuse build configuration templates from an unrelated project, manually move the templates into the common parent project (or the Root project if you want them to be globally available).

Default template for project

Since TeamCity 2017.2, it is possible to define a default template in a project. If defined, it affects all build configurations and subprojects of this project unless other default templates are defined in subprojects. With default templates,  you can easily modify all project's build configurations, for example:

  • add a specific build feature to all build configurations of a project,
  • switch all build configurations to some specific checkout mode,
  • provide a default failure condition.

Anchor
How can I create build configuration template?
How can I create build configuration template?

Managing templates

Creating build configuration template

There are several ways to create a build configuration template:

  • Manually, like a regular build configuration.
  • Extract from an existing build configuration: there is the Extract template option available from the Actions button at the top right corner of the screen. Note that if you extract a template from a build configuration, the original configuration automatically becomes associated with the newly created template.

Defining default template for project

Default templates, available since TeamCity 2017.2, allow affecting all build configurations in this project and its subprojects: you can easilty add a specific build feature to all build configurations of a project, or switch all build configurations to some specific checkout mode, or provide a default failure condition.

You can associate all the build configurations of the project with a default template using the General Settings page of the project administration, by selecting a template from the Default template drop-down. The option is available if at least one template is defined in the project or its parent. All new build configurations will inherit the default template settings.

The settings of the existing configurations will be preserved.

If defined, it affects all build configurations and subprojects of this project unless other default templates are defined in subprojects. With default templates,  you can easily modify all project's build configurations, for example:

  • add a specific build feature to all build configurations of a project,
  • switch all build configurations to some specific checkout mode,
  • provide a default failure condition.

Related settings changes

Since 2017.2  the project configuration schema was changed to accommodate for default templates. 

  • XML: The project-config.xml file now containts the <default-template ref="...." /> element.
  • DSL: Project configuration now contains the defaultTemplate = "..." method. See a sample project configuration with a default template configured:
Code Block
object Project : Project({
    uuid = "2b241ffb-9019-4e60-9a3a-d5475ab1f312"
    extId = "ExampleProject"
    parentId = "_Root"
    name = "Example Project"
    defaultTemplate = "ExampleProject_MyDefaultTemplate" 
    ...
    features {
        ...
    }
	...
})

 

Associating build configurations with templates

  • You can create new build configurations based on a template.
  • You can associate/attach any number of existing build configurations with/to a template: there's the Associate with Template option Template option (Attach to template... since TeamCity 2017.2) available from the Actions button at the top right corner of the screen.

...

You can associate a build configuration to a template only if the template belongs to the current project or one of its parents. A template which has at least one associated build configuration cannot be deleted, the associated build configurations need to be detached first. Since TeamCity 2017.2 you can associate a build configuration with multiple templates. See the dedicated section below. 

Associating build configuration with multiple templates

Since TeamCity 2017.2 a build configuration can be attached to multiple templates using the "Attach to template..." action menu. In the Actions menu, the Manage templates action allows users to:

  • change the order of templates, which affects the overlapping settings priority and the build step order: the priority is given to the settings from the template higher in the list. It affects such entities as parameter names, setting ids (for build steps, triggers, features, artifact dependencies and requirements), VCS roots or snapshot dependency source build configurations ids if they overlap between templates attached to a build configuration. 
  • detach the build configuration from some of the templates (the user marks those to be detached and then has to apply their changes)
  • detach the build configuration from all templates using correspondingly named button on the same dialog window

You can view all the templates attached to a build configuration on the Build Configuration Settings page.

The settings from all templates the build configuration is attached to are inherited and you can view where they are inherited from in the view/edit Build Configuration Settings pages.

When a build configuration is detached from some of its templates, all the effective (i.e. not overridden in the config and not overlapped by some higher priority template) settings inherited from them are copied to the configuration. 

hidden-data
As this EAP version does not support overriding of checkout rules for VCS roots and snapshot dependency options in build configurations yet, no copies of such entities will be created in a build configuration on detaching it from a template if the same VCS root or a dependency on the same build configuration is present in some templates to which the configuration remains attached. This functionality is likely to change when such overriding will become available.
The copying build configuration logic is the same as extracting a template. On moving a build configuration/project, the logic checks all templates to which the build configuration is attached.

Related settings changes

  • XML: If a build configuration is attached to a single template, the resulting config XML format stays the same as it was before ("ref" attribute of the "settings" element).  If it is attached to a number of templates, then references to them are stored in a separate element under "settings" node, as follows:
Code Block
<inherits> 
<ref id="Template1_ExternalId" />
<ref id="Template2_ExternalId />
.....
</inherits>
  • DSL: Kotlin DSL is extended, so within a build type definition users can use the templates(vararg) method accepting either external ids or DSL template instances (but not a mix of them, so if both templates defined inside and outside DSL are used in the same configuration, the external ids of both must be used). The older template(...) method and property cannot be used multiple times within the same build type definition to indicate that it is inherited from multiple templates - following earlier implementation, each time this method is used, it overrides the previous template external id. It is preserved for backward compatibility.

 

Detaching build configurations from template

When you detach a build configuration from a template using the Detach from template option available from the Actions button at the top right corner of the build configuration settings screen, all settings from the template will be copied to the build configuration and enabled for editing.

...

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

 

Associating build configuration with multiple templates

Since TeamCity 2017.2 EAP a build configuration can be attached to multiple templates using the "Attach to template..." action menu. In the Actions menu, the Manage templates action allows users to:

  • change the order of templates, which affects the overlapping settings priority and the build step order: the priority is given to the settings from the template higher in the list. It affects such entities as parameter names, setting ids (for build steps, triggers, features, artifact dependencies and requirements), VCS roots or snapshot dependency source build configurations ids if they overlap between templates attached to a build configuration. 
  • detach the build configuration from some of the templates (the user marks those to be detached and then has to apply their changes)
  • detach the build configuration from all templates using correspondingly named button on the same dialog window

You can view all the templates attached to a build configuration on the Build Configuration Settings page.

The settings from all templates the build configuration is attached to are inherited and you can view where they are inherited from in the view/edit Build Configuration Settings pages.

When a build configuration is detached from some of its templates, all the effective (i.e. not overridden in the config and not overlapped by some higher priority template) settings inherited from them are copied to the configuration. 

hidden-data
As this EAP version does not support overriding of checkout rules for VCS roots and snapshot dependency options in build configurations yet, no copies of such entities will be created in a build configuration on detaching it from a template if the same VCS root or a dependency on the same build configuration is present in some templates to which the configuration remains attached. This functionality is likely to change when such overriding will become available.
The copying build configuration logic is the same as extracting a template. On moving a build configuration/project, the logic checks all templates to which the build configuration is attached.

Related XML settings changes

If a build configuration is attached to a single template, the resulting config XML format stays the same as it was before ("ref" attribute of the "settings" element). If it is attached to a number of templates, then references to them are stored in a separate element under "settings" node, as follows:

<inherits> 
<ref id="Template1_ExternalId" />
<ref id="Template2_ExternalId />
.....
</inherits>

Related DSL changes

Kotlin DSL is extended, so within a build type definition users can use the templates(vararg) method accepting either external ids or DSL template instances (but not a mix of them, so if both templates defined inside and outside DSL are used in the same configuration, the external ids of both must be used). The older template(...) method and property cannot be used multiple times within the same build type definition to indicate that it is inherited from multiple templates - following earlier implementation, each time this method is used, it overrides the previous template external id. It is preserved for backward compatibility.


See also:

Panel
bgColor#FFFFFF
borderStyledashed

Administrator's Guide: Creating and Editing Build Configurations | Configuring Build Parameters