配方 YAML 语法

本文档描述了通用的 YAML 配方语法。要创建自定义 YAML 配方，请编写一个 .yml 定义文件并将其上传到 TeamCity（项目设置 | 配方 | 上传私有配方）。

通用配方结构

TeamCity YAML 配方具有以下结构：

name: myorg/recipe-name
title: The recipe title
version: 1.2.3
description: The recipe description
container: <container properties>
inputs: <input list>
steps: <step list>

  

名称

强制: 是
类型: 字符串

唯一的配方名称。该值必须采用 namespace/recipe-name 格式，其中 namespace 是配方作者拥有的 JetBrains Marketplace 的名称。同一用户上传的所有配方应具有相同的命名空间。请参阅以下 Marketplace 文档文章，了解有关管理用户命名空间的更多信息：上传 TeamCity 配方。

配方和命名空间名称必须为 5–30 个字符长，仅使用字母数字字符、短横线或下划线。它们不能以短横线或下划线开头，也不能包含连续的短横线或下划线。

如果您不打算将配方上传到 JetBrains Marketplace，而仅计划将其用作私有配方，则可以跳过 namespace 部分。单独使用时， recipe-name 的字符限制为 100 个字符（字母数字、短横线和下划线）。

标题

强制: 是（仅适用于上传到 Marketplace 的配方）
类型: 字符串

在 TeamCity UI 中显示的公共配方名称（在添加构建步骤页面、构建日志等中）。

版本

强制: 是（仅适用于上传到 Marketplace 的配方）
类型: 字符串

以 major.minor.patch 格式表示的数字配方版本。 Minor 和 patch 部分对于私有配方是可选的，对于公共配方是必需的。

描述

强制: 是
类型: 字符串

配方的公共描述。私有配方无限制，公共配方最多 1000 个字符。

container

强制: 否
类型: ContainerSettings 对象或字符串

一组属性，用于指定此配方应在其中执行的 Docker 或 Podman 容器。

inputs

强制: 否
类型: List<Input>

在配置配方时，TeamCity UI 中显示的一组编辑器（文本字段、复选框、组合框等）。

steps

强制: 是
类型: List<Step>

构建运行时配方执行的一组构建步骤。

容器设置

配方 container 字段具有以下语法：

container:
  image: alpine
  platform: linux
  parameters: -it

  

如果 image 是唯一必需字段，您可以使用紧凑格式：

container: alpine

除非您指定公共 DockerHub 镜像名称，否则运行配方的构建配置必须具有 Docker 注册表连接以访问注册表。

image

强制: 是
类型: 字符串

从中生成容器的 Docker/Podman 镜像的名称。

平台

强制: 否
类型: 字符串
支持的值： linux | windows

指定容器镜像平台。

参数

强制: 否
类型: 字符串

附加容器运行参数的列表。

输入

输入是配方步骤使用的变量，可由用户自定义。当将独立配方直接添加到构建配置时，可以通过 UI 编辑器根据其类型（文本框用于文本输入，组合框用于选择等）配置输入。

配方还可以通过 uses字段引用其他配方。在这种情况下，输入值通过 YAML 提供，而不是通过 TeamCity UI。

每个输入具有以下格式：

<input-name>:
  type: text
  label: Main label
  description: Input description
  default: value1
  required: true

  

在配方 .yml 文件中，单个输入定义被放置在 inputs 块中：

inputs:
  - env.input_address:
      ...
  - env.input_subject:
      ...
  - env.input_message:
      ...

  

<input-name>

强制: 是
类型: 字符串

存储输入值的构建参数的名称。声明为原始值（不带字段名称）。

您可以同时使用环境变量和常规构建参数作为输入名称。

环境变量（推荐）

以 env. 前缀声明。例如， env.my-input。
步骤可以在不使用参数引用的情况下检索环境变量值。例如， INPUT_VAR="$my-input" 在 Bash 脚本中， System.getenv("my-input") 在 Kotlin 脚本中，等等。
推荐用于除要求用户凭据或其他敏感数据之外的任何输入。敏感值不应存储在环境变量中，因为它们会将这些值暴露给所有子进程和系统工具，从而带来安全隐患。

常规构建参数

声明时不带任何前缀。例如， my-input。
步骤必须使用参数引用来检索其值（例如， string myVal = "%my-input%";）。此语法可能被滥用，用于注入伪装成输入值的恶意代码。因此，常规构建参数仅推荐用于受信任的用户输入。

类型

强制: 是
类型: 字符串
支持的值： 文本 | boolean | select | 密码

输入类型。指定此输入可以具有的值，以及 TeamCity UI 中对应编辑器的外观和行为选项。

文本 — 默认输入类型。允许输入具有任何值。在配方设置中显示一个文本框。
boolean — 将可用输入值的数量限制为 true 或 false。对于此类型的输入，TeamCity 在配方设置中显示复选框。
select — 允许您指定用户可以选择的固定值范围。在 TeamCity UI 中，呈现为组合框编辑器。需要一个额外的 选项 字段来列出可用值：
inputs: - env.retry_timeout: type: select label: Retry timeout required: false default: 60 options: - 5 - 10 - 30 - 60
密码 — 类似于 文本 ，但在 TeamCity UI 和构建日志中用星号掩盖输入值。

label

强制: 否
类型: 字符串

在 TeamCity UI 中显示在编辑器旁边的主要输入标签。公共配方的最大长度为 100 个字符。

描述

强制: 否
类型: 字符串

在 TeamCity UI 中显示在编辑器下方的输入描述。公共配方的最大长度为 250 个字符。

默认

强制: 否
类型: 字符串

初始/默认输入值。如果用户未提供自定义值，步骤将使用此值。如果未设置，请将 required 字段设置为 true。

required

强制: 否
类型: 布尔值

如果用户必须在 TeamCity 配方设置页面上指定输入值，则返回 true ；否则返回 false。如果输入没有 默认 值，请启用此设置。

步长

构建期间执行的一组操作。虽然配方是使用标准 TeamCity 构建步骤的自定义版本的通用构建步骤，但 YAML 配方被设计为通用的，并与任何 TeamCity 代理兼容，无论安装了哪些工具。因此，配方步骤目前只能使用 Kotlin 脚本、命令行步骤和其他 YAML 配方。

一个典型的步骤如下所示：

name: My step
script/kotlin-script/uses: <value>
<containerSettings>

  

在配方 .yml 文件中，单个步骤定义被放置在 steps 块中：

steps:
   - name: First step
     ...
   - name: Second step
      ...
   - name: Third step
      ...

  

名称

强制: 否
类型: 字符串

公共步骤名称。私有配方无限制，公共配方最多 100 个字符。

脚本

强制: 否
类型: 字符串

指定一个使用 TeamCity 命令行步骤执行自定义脚本的步骤。公共配方的最大脚本长度为 50000 个字符。例如，以下步骤将 "Hello world" 打印到构建日志：

name: Script step
script: echo "Hello world"

kotlin-script

强制: 否
类型: 字符串

指定一个使用 TeamCity Kotlin 脚本步骤执行自定义 Kotlin 脚本的步骤。公共配方的最大脚本长度为 50000 个字符。例如，以下步骤将 "Hello world" 打印到构建日志：

name: Kotlin script step
kotlin-script: print("Hello world")

uses

强制: 否
类型: 字符串

引用安装在此 TeamCity 服务器上的另一个配方，并可用于当前配方所在的同一项目。字段值取决于引用的配方是公共的还是私有的：

公共配方： uses: namespace/recipe-name@major.minor.patch。
私有配方： uses: private/recipe-name。

如果引用的配方具有必需的输入，您可以在 inputs 块中指定其值。

以下配方步骤执行版本为 "1.2.3" 的 jetbrains/some_recipe 配方，并将 foo 和条形图值分别传递给 some_recipe 输入 "input1" 和 "input2"。

name: Custom step
uses: jetbrains/some_recipe@1.2.3
inputs:
   input1: foo
   input2: bar

    

container

强制: 否
类型: ContainerSettings 对象或字符串

指定此步骤应运行的 Docker 或 Podman 容器。覆盖此步骤的配方范围内的 container 字段。

以下配方步骤在 Linux 的 "alpine" 容器中运行：

name: Container script step
container:
   image: alpine
   platform: linux
script: echo "Hello world"

    

您可以使用仅指定镜像名称的简短格式：

name: Container script step
container: alpine
script: echo "Hello world"

    

示例

以下 YAML 标记声明了一个具有两个输入的单步骤配方。配方步骤执行一个 Kotlin 脚本，使用 input_name 和 input_value 输入值来生成一个 setParameter 服务消息。当此服务消息打印到构建日志时，TeamCity 会找到 名称 参数并将 值 分配给它。

此配方由 TeamCity 团队创建，并可在 JetBrains Marketplace 上获取： jetbrains/set-environment-variable。

name: jetbrains/set-environment-variable
version: 1.0.0
description: |
  Sets the environment variable to the required value, creating it if absent.
inputs:
  - env.input_name:
      type: text
      required: true
      label: Name
      description: |
        The name of the environment variable to change, without the “env.” prefix. 
        Examples: “PATH”, “JAVA_HOME”, “DOTNET_ROOT”.
  - env.input_value:
      type: text
      required: true
      label: Value
steps:
  - name: Set environment variable
    kotlin-script: |-
      
      @file:Repository("https://download.jetbrains.com/teamcity-repository/")
      @file:DependsOn("org.jetbrains.teamcity:serviceMessages:2024.12")
      
      import jetbrains.buildServer.messages.serviceMessages.ServiceMessage
      import jetbrains.buildServer.messages.serviceMessages.ServiceMessageTypes.BUILD_SET_PARAMETER
      
      val message = ServiceMessage.asString(
          BUILD_SET_PARAMETER,
          mapOf(
              "name" to "env.${requiredInput("name")}",
              "value" to requiredInput("value")
          )
      )
      println(message)
      
      fun requiredInput(name: String) = System.getenv("input_$name") ?: error("Input '$name' is not set.")

  

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