创建并设置自定义参数

这个主题解释了如何创建自定义的 TeamCity 参数，并配置它们的显示和行为。

名称限制

配置参数的名称必须只包含 [a-zA-Z0-9._-*] 字符，并且以 ASCII 字母开头。

如何创建新的参数

在 TeamCity 用户界面

前往 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 中

要在 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")
   }
})

使用 REST API

要通过 TeamCity REST API 创建参数，向所需的端点发送 POST 请求，并在请求体中传递一个属性。

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

请求正文：

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

您还可以向 /app/rest/buildQueue 端点发送请求，仅为单次构建运行创建一次性参数。以下请求以新的密码参数启动新的构建。

/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 &quot;Release&quot; configuration. Otherwise, the &quot;Debug&quot; 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 &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>

最后修改日期： 16日 7月 2024年