Typed Parameters

When adding a Configuring Build Parameters (system property, environment variable, or configuration parameter) you can extend its definition with specification that will regulate parameter's control presentation and validation. This specification is a parameter's "meta" information that is used to display parameter in Triggering a Custom Build dialog. It allows to make custom build run more user-friendly and usable by non-developers. Consider a simple example. You have a build configuration in which you have a monstrous-looking build parameter that regulates if a build has to include license or not; can be either true or false; and by default is false. It may be clear for a build engineer, which build parameter regulates license generation and which value should it have, but it can be not obvious to a regular user. With build parameter's specification you can make your parameters more readable in "Run custom build" dialog. Currently you can present parameters in following forms:

Type	Description
Text	The default. Represents a usual text string without any extra handling
Checkbox	True/false otpion represented with a checkbox.
Select	"Select one" or "select many" control to set the value to one of predefined settings
Password	This is designed to store passwords or other secure data in TeamCity settings. TeamCity makes the value of the password parameter never appear in TeamCity web UI: it affects settings screens and Run Custom Build dialog where the field is presented with password fields. Also, the value is replaced in the build's Build Parameters tab and build log. The value is stored scrambled in the configuration files under TeamCity Data Directory. Please note that build log value hiding is implemented with simple search-and-replace, so if you have a trivial password of "123", all occurrences of "123" will be replaced, potentially exposing the password. Setting the parameter to type password does not guarantee that the raw value cannot be retrieved. Any project administrator can retrieve it and also any developer who can change the build script can in theory write malicious code to get the password.

simple text field with ability to validate its value using regular expression;
check box;
select control;
password field.

To add specification to a build parameter click Edit button in the Spec area when editing/adding a build parameter. All parameters specifications support a number of common properties, such as:

Label: some text which should be shown near the control.
Description: some text that is shown below the control containing explanatory note of the control use.
Display: If hidden is specified, parameter will not be shown in Run Custom Build dialog, but will be sent to a build; if prompt is specified, TeamCity will always require review of parameter value, even if simply run button is clicked; if normal is selected, parameter will be shown as usually.

Depending on the specification's "type", there are additional settings.

Text	Pattern: In this field specify Java-style regular expression to validate field value.
Check box	Check box name: Title of the check box to be displayed in Run Custom Build dialog. Checked value/Unchecked value: Specify values the parameter should have depending on check box's state.
Select Control (Enum)	Items: Specify items for the list. Each item on new line. Use following syntax `label => value` or `value`. Click Allow if you want to enable multiple selection.

Manually configuring parameter's specification

Alternatively you can manually configure a specification using specially formatted string with syntax similar to the one used in service messages (typeName key='value'). For example, for text: text label='some label' regex='some pattern'.

Copying parameter's specification

If you start editing a parameter that has some specification, you can see a link to its raw value in "Edit parameter" dialog. Click it to view the specification in its raw form (in service message format). To use this specification in another build configuration, just copy it from here, and paste in another configuration.

Last modified: 20 April 2023