本文档的内容是由机器翻译的。请通过反馈微件提交您的反馈。
TeamCity On-Premises
 
2025.03
获取 TeamCity On-Premises
  1. 管理构建配置
  2. 配置构建参数
  3. 创建并设置自定义参数

创建并设置自定义参数

最后修改日期： 2025年 3月 21日

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

名称限制

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

如何创建新的参数

在 TeamCity 用户界面

  1. 转到 项目或配置设置并切换到 参数 选项卡。 请参阅此篇文章，获取有关参数优先级和继承规则的信息： 构建参数的作用域、优先级和生命周期。

  2. 切换到 输入参数 选项卡。 输出参数专用于 构建链 ，请参阅本文以获取更多信息： 在构建链中使用参数。

  3. 单击 添加新参数 按钮。

    创建新参数

  4. 指定参数类型并输入参数名称。 请参阅此文章，了解不同参数类型之间的差异更多信息： 配置构建参数。

  5. 选择所需的 值类型 选项。 这些选项控制参数可以具有哪些值。

    • 文本 — 默认类型，允许参数具有任何字符串值。 您可以选择 显示允许值 下的所需选项，以将允许的值限制为仅匹配特定正则表达式模式的值，或确保参数永远不为空。

    • 复选框 — 将可能的参数值数量限制为两个。 在 Run Custom Build （运行自定义构建）对话框中渲染为复选框，允许用户在这些值之间切换。 选中和未选中状态的默认值分别为 true 和 null 比较。 您可以通过 选中值 和 未选中值 字段设置自定义值对（是/否、1/0、调试/发布等）。

    • 密码 — 类似于“文本”类型，“密码”参数可以接受任何字符串作为值。 然而，此值从未在构建之外暴露：TeamCity 会在用户界面，构建日志，DSL 代码和 REST API 响应负载中隐藏这个敏感值。

      密码存储在 TeamCity Data Directory 下的配置文件中。 根据 服务器加密设置 ，该值会被混淆或使用自定义密钥进行加密。

      warning

      密码值通过简单的搜索和替换算法从构建日志中隐藏。 如果您有一个像“123”这样的简单密码，日志中所有出现的“123”字符串将被替换，这可能会暴露密码。

      同样需要注意的是，将参数设置为“Password”类型并不能完全保证您的数据安全。 任何项目管理员都可以检索参数的原始值，而任何可以更改构建脚本的开发人员都可能编写恶意代码以泄露密码。

    • 选择 — 允许您指定一组预定义的值。 调用 Run Custom Build 对话框的用户可以从列表中选择一个或多个值，具体取决于 允许多选 的值。 在 TeamCity UI 中，可以提供带有可选值（例如， Windows => win ）的值。

    • 远程密钥 — 一个值不能手动输入的参数。 相反，当运行构建需要此值时，会从远程存储中安全地检索该值。 参见以下文章以了解更多信息： HashiCorp Vault 集成。

  6. 可选：单击 为“运行自定义构建”对话框自定义设置 以指定影响运行 custom builds 的用户的其他选项。

    • 显示 — 指定用户是否可以（或应该）编辑此参数。

      • Normal 参数是显示在 Run Custom Build 对话框中的默认参数。

      • 隐藏 参数在 Run Custom Build 对话框中不可见。 将此类型用于不希望用户看到的服务参数。 与秘密参数不同，可以将隐藏参数的值回显到构建日志，通过 REST API 请求等等。

      • 提示 参数在每次用户触发新构建时调用 Run Custom Build 对话框，以确保为每次运行提供有效值。 您也可以使用此类型来实现自定义确认对话框（请参阅下面的示例部分）。

    • 描述 和 Label 字段允许您添加提示，帮助用户选择正确的参数值。

      参数标签和描述

    • 只读 参数在 Run Custom Build 对话框中显示禁用的编辑器，这可以防止用户更改参数值。 如果除了锁定值外，您还希望对用户隐藏此参数，请将 显示 选项设置为 隐藏。

  7. 可选项：如果您的自定义参数应具有默认值，请在相应的字段中输入。 如果您希望在子项目或配置中设置最终参数值、在构建过程中计算，或者需要不同的代理报告此参数的不同值，您也可以将此字段留空。 请阅读以下文章，了解更多可用值来源： 构建参数的作用域、优先级和生命周期。

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

从构建步骤

发送 ##teamcity[setParameter name='ddd' value='fff'] 服务消息以更新参数值，或者如果尚不存在具有此名称的参数，则创建一个新参数。

请参阅此文章以获取更多信息： 添加或更改构建参数。

创建一个密钥

密钥是一个包含敏感数据的参数，必须安全存储以防止泄漏。 根据您的场景和预期用途，您有以下选项。

密码参数

如果您希望密钥值存储并在特定配置或项目中使用，请按照 在 TeamCity 用户界面 部分中描述的方式创建一个 密码类型的常规输入参数。

远程密钥

如果您有一个存储值的外部密钥库，请创建一个 远程密钥类型的参数。 通过额外配置的密钥库连接，这些参数可以按需安全地检索值。

目前，仅支持 HashiCorp Vault 密钥存储。

请参阅以下文章以了解更多信息： HashiCorp Vault 集成

令牌

如果您的项目将设置存储 在远程 VCS 中 ，您可能需要在不暴露它们的情况下配置密钥值。 为此，请创建一个服务器端令牌来存储密钥，然后将其名称作为参数值传递。

请参阅此主题以获取更多信息： 管理 Tokens

加密的密钥

您还可以在不使用版本化设置的情况下创建令牌。 在这种情况下，令牌只能在存储在磁盘上的项目配置文件中使用（在 TeamCity Data Directory（TeamCity 数据目录） 中）。

要创建此类令牌，请调用项目 操作菜单并单击 加密安全值...。

加密值

在弹出的对话框中，输入一个密钥值并点击 加密。 在关闭对话框之前，请记得复制加密的值。

使用 REST API

要通过 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"/>

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

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

参阅此文章以了解更多关于通过 REST API 管理参数的信息： 管理类型参数。

在默认属性文件中

这种方法允许您声明只对那些共享同一 VCS 根的构建配置有效的参数。 以这种方式定义的参数在 TeamCity UI 中不可见，并直接传递给构建过程。

  1. 以 teamcity.default.properties 作为名称创建一个文本文件。

  2. 将参数以 系统.<名称>=<值> 或 env.<名称>=<值> 的格式填充进去。 例如， env.CATALINA_HOME=C:\tomcat_6.0.13。

  3. 将此文件推送到目标仓库的根目录。

  4. 设置所需的 签出设置 并确保文件签出到 Build Working Directory（构建工作目录）。

您可以通过构建配置的 teamcity.default.properties 参数修改属性文件的名称和路径。

示例

复选框参数

此参数在 运行自定义构建 对话框中显示一个复选框。 参数可在 release （已选中）和 调试 （未选中）值之间切换。

复选框参数
复选框参数设置

正则表达式参数

此参数只接受与给定正则表达式相匹配的字符串值。 如果输入无效值，TeamCity 不允许运行新的构建。

正则表达式参数
RegEx 参数设置

单选参数

此参数定义了多个值，但只允许用户一次选择一个值。 值以组合框项的形式显示在 运行自定义构建 对话框中。

单选参数 1
单选参数 2
单选参数设置

多选参数

此参数允许用户从预定义列表中选择多个值。

多选参数

如果选择了多个项目，参数会使用指定的分隔符字符连接它们的值。 例如，如果分隔符从默认的逗号（, ）更改为垂直条（| ），参数值看起来如下： 2023.03|2023.11|2024.03。

多选参数用户界面设置

确认对话框

如果配置具有 提示 类型参数，则每次用户尝试运行新构建时，都会弹出 Run Custom Build 对话框。 只有在用户为此参数输入有效值后，才会开始构建。 您可以利用此行为来实现一个自定义确认对话框，以防止配置过度运行。

开始提示
提示对话框设置

See also

Administrator's Guide