Features How-To's Tips & Tricks

Overriding Template Settings

It’s quite a typical case when you need to create several more or less similar build configurations in TeamCity, for example, to run builds in different environments, or create a separate build configuration for release builds, etc. Of course, you can simply copy build configurations, but what if you’ll need to change, for example, a VCS root in all of them? Naturally, you’ll have to manually change it in every configuration. Don’t you think it’s too much of routine work? We thought so too, that’s why in TeamCity there are build configuration templates. You can create a template with common (shared) settings and then inherit any number of build configurations from this template, or you can extract a template from any of your existing build configurations. Thus, when you’ll need to change some setting in all template-based configurations, you’ll just change it in the template.

One might ask what to do if you need to override a setting inherited from a template in one of the build configurations. If your template defines a specific value for this setting, every template-based configuration will have the same value and since it’s inherited it’ll be a display-only field. But there’s a trick! You can use a configuration parameter instead of an actual value in the template. Basically, such parameter is used inside TeamCity only, and it is not passed to an actual build, but it provides you with means to make your templates flexible.
Here’s an example to illustrate how it works. Let’s say I need to redefine Maven goals in my build configurations based on the same template. In the template settings, instead of actual goals I’ll introduce a configuration parameter:

Note, the syntax here is elementary – %ParameterName%. Now, if I’ll go to the Properties and Environment Variables section, I’ll see there this configuration parameter.

I can define a default value for goals, or leave it as is – in this case I’ll have to define it in every child configuration manually. Let’s say, the default should be test.

Now, I’ll switch to the build configuration based on this template where I’d like to have deploy goal instead of test, and redefine it there.

In our docs, you’ll find the list of settings that can and cannot be overridden with configuration templates. However that’s not the only use case for the configuration parameters. Now they are also used as some of the agent’s parameters, for example for .NET Framework/SDK/Visual Studio/Mono detected on an agent. These we’ll describe in detail in the next post, so stay tuned!

image description