创建并设置自定义参数
这个主题解释了如何创建自定义的 TeamCity 参数,并配置它们的显示和行为。
配置参数的名称必须只包含 [a-zA-Z0-9._-*]
字符,并且以 ASCII 字母开头。
前往 Project Settings (项目设置)或者 Build Configuration Settings (构建配置设置)页面,并切换到 Parameters (参数)选项卡。 请参阅此篇文章,获取有关参数优先级和继承规则的信息:构建参数的作用域、优先级和生命周期。
点击 Add new parameter (添加新参数)按钮。
指定参数类型并输入参数名称。 请参阅此文章,了解不同参数类型之间的差异更多信息:配置构建参数。
选择所需的 Value type 选项。 这些选项控制参数可以具有哪些值。
Text—— 默认类型,允许参数具有任何字符串值。 您可以选择在 Show allowed value (显示允许的值)下选择一个必需的选项,以将允许的值限制为仅匹配特定 RegEx 模式的值,或确保参数永不为空。
Checkbox—— 将可能的参数值限制为两个。 在 Run Custom Build (运行自定义构建)对话框中渲染为复选框,允许用户在这些值之间切换。 选中和未选中状态的默认值分别为
true
和null 比较
。 您可以通过 Checked value (已选值)和 Unchecked value (未选值)字段设置您的自定义值对(是/否,1/0,debug/release 等)。Password — 类似于 "Text" 类型,“Password” 参数可以接受任何字符串作为值。 然而,此值从未在构建之外暴露:TeamCity 会在用户界面,构建日志,DSL 代码和 REST API 响应负载中隐藏这个敏感值。
Select—— 允许您指定一组预定义值。 调用 Run Custom Build (运行自定义构建)对话框的用户可以从列表中选择一个或多个值,这取决于 允许多项选择 的值。 在 TeamCity UI 中,可以提供带有可选值(例如,
Windows => win
)的值。远程秘钥—— 一种参数,其值不能手动输入。 相反,当运行构建需要此值时,会从远程存储中安全地检索该值。 参见以下文章以了解更多信息:HashiCorp Vault 集成。
可选操作:点击 自定义 "Run Custom Build" 对话框的设置 ,指定影响运行 自定义构建 的用户的额外选项。
显示 — 指定用户是否可以(或应)编辑此参数。
Normal(标准)参数是在 Run Custom Build (运行自定义构建)对话框中显示的默认参数。
Hidden(隐藏)参数在 Run Custom Build (运行自定义构建)对话框中不可见。 将此类型用于不希望用户看到的服务参数。 与秘密参数不同,可以将隐藏参数的值回显到构建日志,通过 REST API 请求等等。
Prompt (提示)参数每次用户触发新的构建时,都会调用 Run Custom Build 对话框,以确保为每次运行提供有效的值。 您也可以使用此类型来实现自定义确认对话框(请参阅下面的示例部分)。
描述和标签字段允许您添加提示,帮助用户选择正确的参数值。
Read-only (只读)参数在 Run Custom Build (运行自定义构建)对话框中显示为禁用的编辑器,阻止用户更改参数值。 如果您除了锁定值之外,还希望从用户那里隐藏此参数,请将 Display 选项设置为 Hidden。
可选项:如果您的自定义参数应具有默认值,请在相应的字段中输入。 如果您希望在子项目或配置中设置最终参数值、在构建过程中计算,或者需要不同的代理报告此参数的不同值,您也可以将此字段留空。 请阅读以下文章,了解更多可用值来源:构建参数的作用域、优先级和生命周期。
要在 Kotlin DSL 中定义自定义参数,请将 param("prefix.name", "value")
行添加到项目或构建配置的 形参
部分。
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")
}
})
要通过 TeamCity REST API 创建参数,向所需的端点发送 POST 请求,并在请求体中传递一个 属性。
POST <SERVER_URL>/app/rest/projects/MyProject/parameters
# or
POST <SERVER_URL>/app/rest/buildTypes/MyProject_MyConfig/parameters
请求正文:
<property name="parameter.from.rest" value="custom_value"/>
{
"name" : "parameter.from.rest",
"value" : "custom_value"
}
您还可以向 /app/rest/buildQueue
端点发送请求,仅为单次构建运行创建一次性参数。 以下请求以新的密码参数启动新的构建。
POST/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"
}
}]
}
}
参阅此文章以了解更多关于通过 REST API 管理参数的信息:管理类型参数。
这种方法允许您声明只对那些共享同一 VCS 根的构建配置有效的参数。 以这种方式定义的参数在 TeamCity UI 中不可见,并直接传递给构建过程。
以
teamcity.default.properties
作为名称创建一个文本文件。将参数以
系统.<名称>=<值>
或env.<名称>=<值>
的格式填充进去。 例如,env.CATALINA_HOME=C:\tomcat_6.0.13
。将此文件推送到目标仓库的根目录。
设置所需的 签出设置 并确保文件签出到 Build Working Directory(构建工作目录)。
您可以通过构建配置的 teamcity.default.properties
参数修改属性文件的名称和路径。
此参数在 Run Custom Build (运行自定义构建)对话框中显示一个复选框。 参数可在 发布
(已选中)和 调试
(未选中)值之间切换。


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 载荷:
{
"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 载荷:
<property 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'"/>
</property>
此参数只接受与给定正则表达式相匹配的字符串值。 如果输入无效值,TeamCity 不允许运行新的构建。


object MyBuildConfig : BuildType({
params {
text("EmailRegExParam",
"johndoe@jetbrains.com",
regex = """^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}${'$'}""",
validationMessage = "Invalid email address")
}
})
JSON 载荷:
{
"name": "EmailRegExParam",
"value": "johndoe@jetbrains.com",
"type": {
"rawValue": "text regexp='^|[\\w-\\.|]+@(|[\\w-|]+\\.)+|[\\w-|]{2,4}$' validationMode='regex' validationMessage='Invalid email address' display='normal'"
}
}
XML 载荷:
<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>
此参数定义了多个值,但只允许用户一次选择一个值。 值作为组合框项在 Run Custom Build (运行自定义构建)对话框中显示。



object MyBuildConf : BuildType({
params {
select("SingleSelectParam",
"linux",
options = listOf(
"Windows" to "win",
"Linux" to "linux",
"macOS" to "mac"
)
)
}
})
JSON 载荷:
{
"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 载荷:
<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>
此参数允许用户从预定义列表中选择多个值。

如果选择了多个项目,参数会使用指定的分隔符字符连接它们的值。 例如,如果分隔符从默认的逗号( ,
)更改为垂直条( |
),参数值看起来如下: 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 载荷:
{
"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 载荷:
<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>
如果配置具有 prompt 类型参数,每当用户尝试运行新的构建时,Run Custom Build (运行自定义构建)对话框都会弹出。 只有在用户为此参数输入有效值后,才会开始构建。 您可以利用此行为来实现一个自定义确认对话框,以防止配置过度运行。


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 载荷:
{
"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 载荷:
<property 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'"/>
</property>
感谢您的反馈!