Create and Set Up Custom Parameters

Parameters with this display mode are not shown in the Run Custom Build dialog when a user triggers a custom build. Choose this mode to hide parameters you do not want users to see.

If you want to prevent users from editing a parameter value but still leave the parameter visible, leave the display mode as "Normal" and tick the Read-only checkbox instead.

If a build configuration has a parameter of the "Prompt" type, every time a user triggers a new build, the Run Custom Build dialog appears. This behavior ensures that a user sets a valid value for all "Prompt" parameters before the build process starts.

For example, the following parameter adds a run confirmation to your build configuration: users cannot start new builds unless they type "deploy" in the corresponding field.

object MyBuildConf : BuildType({
params {
    text("launch.confirmation", "",
            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""")
    }
})

This is the default editor type. Parameters of this type display a regular text box. Choose this type to apply an input mask for user values.

For example, the following parameter uses a regular expression to accept only e-mail addresses:

object PromptTest : BuildType({
   params {
       text("a.text.mail.param", "", label = "Email Address",
               regex = """^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}${'$'}""",
               validationMessage = "Invalid e-mail address")
   }
})

Choose this type to display a checkbox next to the parameter label.

By default, the checked editor corresponds to the true value; otherwise, the parameter has no value. Use the Checked value and Unchecked value to provide custom values.

The initial checkbox state depends on the default parameter value.

tip

The editor supports only checked and unchecked states; the indeterminate state is not allowed. However, if the default (initial) parameter value corresponds to neither checked nor unchecked states, the parameter can report three potential values.

object PromptTest : BuildType({
   params {
      checkbox("checkbox.param", "value-not-set",
      label = "Checkbox parameter", description = "",
      checked = "checked", unchecked = "unchecked")
   }
})

The default value applies during regular builds, checked and unchecked values are used in custom build runs.

Choose this editor type to hide the parameter value.

Password parameter values are hidden not only from the TeamCity UI, but also from DSL code (visible via the View as code button and saved to a remote repository when you enable versioned settings).

object PromptTest : BuildType({
   params {
       password("a.password.param", "******", label = "Registry password")
   }
})

Requesting parameters via REST API also returns a payload without parameter values.

GET
<SERVER_URL/app/rest/buildTypes/MyBuildConfig/parameters?locator=name:password.param

Response payload:

<properties count="1">
    <property name="password.param">
        <type rawValue="password display='normal' label='Registry password'"/>
    </property>
</properties>

{
    "count": 1,
    "property": [
        {
            "name": "password.param",
            "type": {
                "rawValue": "password display='normal' label='Registry password'"
            }
        }
    ]
}

If you need to create a password parameter not in TeamCity UI, you can use secure value tokens to set up parameter values.

params {
   password("my.password.param", "credentialsJSON:<token>")
}

Choose this editor type to display a combo box next to the parameter label and limit the range of possible values by multiple predefined options.

Each item of the editor drop-down menu has a publicly visible label and an underlying value assigned to the parameter. In TeamCity UI, use the label => value syntax to set different strings or value if you want them to match. In Kotlin DSL, use the "label" to "value" syntax.

The following sample illustrates a parameter that allows users to select a value passed to the VCS Labeling build feature.

object MyBuildConf : BuildType({
    name = "Select Parameter Sample"

    params {
        select("release.status", "", label = "Deployment Tag",
                options = listOf("EAP" to "eap",
                        "CTP" to "ctp",
                        "Alpha preview" to "alpha",
                        "Beta preview" to "beta",
                        "Release" to "release")
        )
    }

features {
    vcsLabeling {
        vcsRootId = "${MavenRepoRootGithub.id}"
        labelingPattern = "%release.status%"
    }
}
})

If the Allow multiple selection option is enabled, users can tick multiple options at once.

In this case, the parameter value is a string that contains values of all selected items separated by a given char.