TeamCity On-Premises 2021.2 Help

Changing Build Parameter Type and UI Appearance

When adding a build 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 (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. However, if a user wants to run a custom build, the variety of available parameters might confuse them. Using the build parameter specification, you can make the parameters' appearance in the Run Custom Build dialog more readable.

Typed parameter in a Running Custom Build dialog

Adding Parameter Specification

To add a specification to a build parameter, click Edit in the Spec section when editing/adding a build parameter.

All parameter specifications support the following common settings:

Setting

Description

Label

An alternative text that can be displayed near the control in the Run Custom Build dialog.

Description

A text that is displayed below the control. Might contain a more detailed explanation on how to use the control.

Display

A display mode:

  • Hidden: the parameter will not be displayed in the Run Custom Build dialog, but will be sent to a build.

  • Prompt: TeamCity will always require a review of the parameter's value when clicking Run (except if the build is triggered automatically).

  • Normal: the parameter will be displayed as usual, on the Parameters tab of the Run Custom Build dialog.

Read-only

If enabled, it will be impossible to override the parameter's default value.

Type

A UI field type:

Types of Parameters

Text Type

This is the default option which is a usual text string.

For this type, it is possible to define the allowed value:

Checkbox Type

A true/false option represented by a checkbox.

For this type, it is possible to specify the values of the parameter that will be applied depending on the checkbox state (true or false).

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:

  • If the build is triggered by an automatic trigger or by clicking Run (without the Run Custom Build dialog), the default value is used.

  • If the build is triggered via the Run Custom Build dialog without changing anything, the "unchecked" value is used, if it is not empty and differs from the default one. If empty, the default value is used.

  • If the build is triggered via the Run Custom Build dialog with the box checked, the "checked" value is used, if it is not empty. If it is empty, the true value is used.

Select Type

A "select one" or "select many" control to set the value to one of the predefined settings.

To allow selection of multiple options, enable the Allow multiple option. In the Items field, specify a newline-separated list of items of the selector menu. Use the following syntax label => value to display a human-readable label to represent a value or just value to display the value as is.

Password Type

This type is designed to store passwords or other secure data in TeamCity settings. The value of the password parameter never appears readable in the TeamCity UI, including the settings' screens and the Run Custom Build dialog. 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.

Note that if you switch an existing parameter from the Password type to any other type, the original password value will be lost.

Manually Configuring Parameter Specification

You can also configure a parameter's specification manually — 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, use 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 it in another configuration.

Modifying Parameter Specification via REST API

You can also view/edit typed parameters' specification via REST API.

Last modified: 17 January 2022