Typed Parameters
When adding a build parameter (system property, environment variable, or configuration parameter), you can extend its definition with meta-information, or specification. The parameter's specification defines how its controls are presented and validated in the Run Custom Build dialog.
By adding a typed specification to a parameter, you make it a typed parameter. Typed parameters are more understandable for non-developers and make experience with builds more user-friendly.
Example: a build configuration has a parameter that defines if a build has to include a license or not. The parameter can be either true or false, and is false by default. For a regular user, it might not be clear which build parameter is responsible for the license generation and what its values mean. It is not a problem when builds run with the default configuration, but if some user wants to run a custom build, the variety of available parameters might confuse them. Using the build parameter's specification, you can make the parameters' appearance in the Run Custom Build dialog more readable.
Adding Parameter Specification
To add a specification to a build parameter, click Edit in the Spec section when editing/adding a build parameter.
All parameters' specifications support the following common properties:
Label: a text that is displayed near the control in the Run Custom Build dialog.
Description: a text that is displayed below the control containing an explanatory note of the control use.
- Display:
if hidden is selected, the parameter will not be displayed in the Run Custom Build dialog, but will be sent to a build;
if prompt is selected, TeamCity will always require a review of the parameter's value when clicking Run (won't require the parameter if the build is triggered automatically);
if normal is selected, the parameter will be displayed as usual.
Read-only: if enabled, it will be impossible to override the parameters value.
- Type:
a simple text field with the ability to validate its value using a regular expression;
a checkbox;
a select control;
a password field.
The table below provides more details on each control type.
Type | Description |
|---|---|
Text | The default option. Represents a usual text string without any extra handling. |
Checkbox | A true/false option represented by a checkbox. |
Select | A "select one" or "select many" control to set the value to one of the predefined settings. |
Password | This type is designed to store passwords or other secure data in TeamCity settings. TeamCity makes the value of the password parameter never appear in the TeamCity UI: including the settings' screens and the Run Custom Build dialog where password fields appear. The value is also replaced in the build's Parameters tab and build log. The password value is stored in the configuration files under TeamCity Data Directory. Depending on the server encryption settings, the value is either scrambled or encrypted with a custom key. The build log value is hidden with a simple search-and-replace algorithm, so if you have a trivial password of "123", all occurrences of "123" will be replaced, potentially exposing the password. Setting the parameter to the password type does not guarantee that the raw value cannot be retrieved. Any project administrator can retrieve it, and any developer who can change the build script could potentially write malicious code to get the password. Note that if you switch an existing parameter from the password type to any other type, the original password value will be lost. |
Depending on the specification's type, there are additional settings.
Text | Allowed value: choose the allowed text value. For the Regex option, specify Pattern, a Java-style regular expression to validate the field value, as well as a validation message. |
Checkbox | Checked value/Unchecked value: Specify values of the parameter respective to these checkbox states. We recommend that you keep the unchecked value equal to the default value and specify a custom checked value. Depending on how the build is triggered, the checkbox behavior will be as follows:
|
Select | Check the Allow multiple box to enable multiple selection. In the Items field, specify a newline-separated list of items. Use the following syntax |
Manually Configuring Parameter Specification
Alternatively, you can manually configure a specification using a specially formatted string with the syntax similar to the one used in service messages (typeName key='value').
For example, for the text label: text label='some label' regex='some pattern'.
Copying Parameter Specification
If you start editing a parameter that has a specification, you can see a link to its raw value in the Edit parameter dialog. Click it to view the specification in its raw form (in the service message format). To use this specification in another build configuration, just copy it from here, and paste in another configuration.
Modifying Parameter Specification via REST API
You can also view/edit typed parameters specification via REST API.