Create and Set Up Custom Parameters
This topic explains how to create custom TeamCity parameters and configure their appearance and behavior.
Name Restrictions
The names of configuration parameters must contain only the [a-zA-Z0-9._-*] characters and start with an ASCII letter.
How to Create a New Parameter
In TeamCity UI
Go to the Project Settings or Build Configuration Settings page and switch to the Parameters tab. See this article for information on parameter priority and inheritance rules: Scopes, Priority, and Lifecycle of Build Parameters.
Click the Add new parameter button.
Specify the parameter kind and enter the parameter name. See this article for more information on the difference between different parameter types: Configuring Build Parameters.
Choose the required Value type option. These options control what values a parameter can have.
Text — the default type that allows the parameter to have any string value. You can optionally choose a required option under Show allowed value to limit the allowed values to only those that match the specific RegEx pattern, or ensure a parameter is never empty.
Checkbox — limits the number of possible parameter values to two. Rendered as a checkbox in the Run Custom Build dialog, allowing users to toggle between these values. The default values for checked and unchecked states are
trueandnullrespectively. You can set up your custom value pairs (yes/no, 1/0, debug/release, and so on) via the Checked value and Unchecked value fields.Password — similar to the "Text" type, "Password" parameters can accept any string as a value. However, this value is never exposed outside a build: TeamCity hides this sensitive value from the UI, build logs, DSL code, and REST API response payloads.
Select — allows you to specify a set of predefined values. Users that invoke the Run Custom Build dialog can choose one or multiple values from the list, depending on the Allow multiple selection value. Values can be supplied with optional values displayed in TeamCity UI (for example,
Windows => win).Remote secret — a parameter whose value cannot be entered manually. Instead, a value is securely retrieved from a remote storage when the running builds needs this value. See the following article to learn more: HashiCorp Vault Integration.
Optional: Click Customize settings for the "Run Custom Build" dialog to specify additional options that affect users who run custom builds.
Display — specifies whether users can (or should) edit this parameter.
Normal parameters are default parameters that are shown in the Run Custom Build dialog.
Hidden parameters are not visible in the Run Custom Build dialog. Use this type for service parameters that you do not want users to see. Unlike with secret parameters, it is possible to echo a value of a hidden parameter to a build log, request it via REST API, and so on.
Prompt parameters invoke the Run Custom Build dialog every time users trigger a new build to ensure a valid value is provided for each run. You can also use this type to implement custom confirmation dialogs (see the Examples section below).
Description and Label fields allow you to add hints that help users choose a correct parameter value.
Read-only parameters display disabled editors in the Run Custom Build dialog, which prevents users from changing parameter values. If along with locking the value you also want to hide this parameter from users, set the Display option to Hidden.
Optional: If your custom parameter should have a default value, enter it in the corresponding field. You can also leave this field empty if the final parameter value should be set in child projects or configurations, calculated during a build, or if you need different agents to report different values for this parameter. See the following article to learn more about available value sources: Scopes, Priority, and Lifecycle of Build Parameters.
In Kotlin DSL
To define a custom parameter in Kotlin DSL, add the param("prefix.name", "value") line to the params section of a project or build configuration.
Using REST API
To create a parameter via TeamCity REST API, send the POST request to the required endpoint and pass a Property as a request body.
Request body:
You can also send requests to the /app/rest/buildQueue endpoint to create one-time parameters for a single build run only. The following request starts a new build with a new password parameter.
See this article to learn more about managing parameters via REST API: Manage Typed Parameters.
In the Default Properties File
This method allows you to declare parameters available only for those build configurations that share the same VCS root. Parameters defined this way are not visible in the TeamCity UI and are passed directly to the build process.
Create a text file with the
teamcity.default.propertiesname.Populate it with parameters in the
system.<name>=<value>orenv.<name>=<value>format. For example,env.CATALINA_HOME=C:\tomcat_6.0.13.Push this file to the root directory of the target repository.
Set up required checkout settings and ensure the file checks out to the Build Working Directory.
You can modify the name and path to the properties file via the teamcity.default.properties parameter of a build configuration.
Examples
Checkbox parameter
This parameter shows a checkbox in the Run Custom Build dialog. The parameter can be toggled between release (checked) and debug (unchecked) values.
JSON payload:
XML payload:
RegEx Parameter
This parameter accepts only string values that match the given regular expression. TeamCity does not allow running a new build if an invalid value is entered.
JSON payload:
XML payload:
Single-Select Parameter
This parameter defines multiple values but allows users to select only one value at a time. Values are displayed as combobox items in the Run Custom Build dialog.
JSON payload:
XML payload:
Multi-Select Parameter
This parameter allows users to select multiple values from the predefined list.
If multiple items are selected, the parameter joins their values using the specified separator char. For example, if the separator was changed from a default comma (,) to a vertical bar (|), the parameter value looks like the following: 2023.03|2023.11|2024.03.
JSON payload:
XML payload:
Confirmation Dialog
If a configuration has a prompt type parameter, every time a user attempts to run a new build the Run Custom Build dialog pops up. The build will start only after a user enters a valid value for this parameter. You can use this behavior to implement a custom confirmation dialog that protects a configuration from excessive runs.
JSON payload:
XML payload: