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 true and null respectively. 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.
  Password values are hidden from the build log by a plain search-and-replace algorithm. If you have a trivial password such as "123", all occurrences of the "123" string will be replaced in the log, which could potentially expose the password.
  It is also important to remember that setting the parameter to the "Password" type does not completely guarantee the safety of your data. Any project administrator can retrieve the parameter's raw value, and any developer who can change the build script can potentially write malicious code to leak the password.
- 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.

import jetbrains.buildServer.configs.kotlin.*

// Project-level Parameters
project {
   params {
      param("env.ProjectLevelParam", "/System/DriverKit")
      param("ProjectLevelParam", "true")
   }
}

// Build Configuration-level Parameters
object MyBuildConf : BuildType({
   params {
       param("ConfigLevelParam", "24")
       param("env.ConfigLevelParam", "CTP")
   }
})

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.

POST <SERVER_URL>/app/rest/projects/MyProject/parameters
# or
POST <SERVER_URL>/app/rest/buildTypes/MyProject_MyConfig/parameters

Request body:

{
  "name" : "parameter.from.rest",
  "value" : "custom_value"
}

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.

/app/rest/buildQueue

<build>
   <buildType id="MyBuildConfID"/>
   <properties>
      <property name="env.password" value="mySecret">
         <type rawValue="password"/>
      </property>
   </properties>
</build>

{
   "buildType": {
      "id": "MyBuildConfID"
   },
   "properties": {
      "property": [{
         "name": "env.password",
         "value": "mySecret",
         "type": {
            "rawValue": "password"
         }
      }]
   }
}

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.properties name.
Populate it with parameters in the system.<name>=<value> or env.<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.

object Test : BuildType({
   name = "Test"
   params {
      checkbox("CheckBoxDefaultParam",
              "debug", // Initial value
              label = "Release configuration",
              description = """Check to run the build in "Release" configuration. Otherwise, the "Debug" configuration is used.""",
              display = ParameterDisplay.PROMPT,
              checked = "release",
              unchecked = "debug")
   }
})

JSON payload:

{
  "name": "CheckBoxDefaultParam",
  "value": "debug",
  "type": {
    "rawValue": "checkbox description='Check to run the build in \"Release\" configuration. Otherwise, the \"Debug\" configuration is used.' label='Release configuration' uncheckedValue='debug' checkedValue='release' display='prompt'"
  }
}

XML payload:

<property name="CheckBoxDefaultParam" value="debug">
    <type rawValue="checkbox description='Check to run the build in &quot;Release&quot; configuration. Otherwise, the &quot;Debug&quot; configuration is used.' label='Release configuration' uncheckedValue='debug' checkedValue='release' display='prompt'"/>
</property>

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.

object MyBuildConfig : BuildType({
   params {
      text("EmailRegExParam",
           "johndoe@jetbrains.com",
           regex = """^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}${'$'}""",
           validationMessage = "Invalid email address")
   }
})

JSON payload:

{
    "name": "EmailRegExParam",
    "value": "johndoe@jetbrains.com",
    "type": {
        "rawValue": "text regexp='^|[\\w-\\.|]+@(|[\\w-|]+\\.)+|[\\w-|]{2,4}$' validationMode='regex' validationMessage='Invalid email address' display='normal'"
    }
}

XML payload:

<property name="EmailRegExParam" value="johndoe@jetbrains.com">
    <type rawValue="text regexp='^|[\w-\.|]+@(|[\w-|]+\.)+|[\w-|]{2,4}$' validationMode='regex' validationMessage='Invalid email address' display='normal'"/>
</property>

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.

object MyBuildConf : BuildType({
   params {
      select("SingleSelectParam",
              "linux",
              options = listOf(
                      "Windows" to "win",
                      "Linux" to "linux",
                      "macOS" to "mac"
              )
      )
   }
})

JSON payload:

{
  "name": "SingleSelectParam",
  "value": "linux",
  "type": {
    "rawValue": "select data_5='mac' label_5='macOS' label_3='Linux' display='normal' data_1='win' label_1='Windows' data_3='linux'"
  }
}

XML payload:

<property name="SingleSelectParam" value="linux">
    <type rawValue="select data_5='mac' label_5='macOS' label_3='Linux' display='normal' data_1='win' label_1='Windows' data_3='linux'"/>
</property>

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.

object Test : BuildType({
   name = "Test"
   params {
      select("MultiSelectParam",
              "2023.03",
              allowMultiple = true,
              valueSeparator = "|",
              options = listOf(
                      "master" to "2023.03",
                      "2023.05",
                      "2023.11",
                      "2024.03",
                      "2024.06"))
   }
})

JSON payload:

{
  "name": "MultiSelectParam",
  "value": "2023.03",
  "type": {
    "rawValue": "select data_6='2024.06' data_5='2024.03' display='normal' multiple='true' valueSeparator='||' data_1='2023.03' label_1='master' data_4='2023.11' data_3='2023.05'"
  }
}

XML payload:

<property name="MultiSelectParam" value="2023.03">
    <type rawValue="select data_6='2024.06' data_5='2024.03' display='normal' multiple='true' valueSeparator='||' data_1='2023.03' label_1='master' data_4='2023.11' data_3='2023.05'"/>
</property>

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.

object Test : BuildType({
   name = "Test"
   params {
      text("PromptConfirmation",
              "",
              label = "Deployment build confirmation",
              description = "This configuration triggers the deployment chain, which uploads updated NuGet packages and Docker images to public sources. Do you want to continue?",
              display = ParameterDisplay.PROMPT, 
              regex = "deploy",
              validationMessage = """Type "deploy" to run this build""")
   }
})

JSON payload:

{
  "name": "PromptConfirmation",
  "value": "",
  "type": {
    "rawValue": "text regexp='deploy' validationMessage='Type \"deploy\" to run this build' display='prompt' description='This configuration triggers the deployment chain, which uploads updated NuGet packages and Docker images to public sources. Do you want to continue?' label='Deployment build confirmation' validationMode='regex'"
  }
}

XML payload:

<property name="PromptConfirmation" value="">
    <type rawValue="text regexp='deploy' validationMessage='Type &quot;deploy&quot; to run this build' display='prompt' description='This configuration triggers the deployment chain, which uploads updated NuGet packages and Docker images to public sources. Do you want to continue?' label='Deployment build confirmation' validationMode='regex'"/>
</property>

Last modified: 18 September 2024