管道设置 | TeamCity On-Premises 文档

编辑管道设置

若要查看和编辑核心管道设置，请点击右上角的设置切换，然后点击可视化编辑器中作业周围的管道画布区域的任意位置。

您还可以从可视化编辑器切换到代码，直接编辑标记。

参数

参数是名称－值对，用于将原始值替换为引用。当 TeamCity 遇到参数引用（%\参数名称% ）时，会将其替换为实际的参数值。

TeamCity 支持两种参数层级：pipeline 参数和 job 参数。流水线参数同时可作为输入参数和输出参数。

作业参数},{ 被设计用于这些作业，以及依赖它的作业（通过 job.<source-job-ID>.<param-name> 语法）。如需了解详情，请参阅作业参数。
管道输入参数会在同一管道内的所有作业之间共享。下方示例演示了一个管道参数被传递到两个作业中。
parameters: PipelineParam: foo jobs: Job1: name: Job 1 steps: - type: script script-content: 'echo "Pipeline parameter: %PipelineParam%"' # prints 'foo' Job2: name: Job 2 dependencies: - Job1 parameters: env.Job2Param: '%PipelineParam% bar' # job parameter references pipeline input param steps: - type: script script-content: |- echo "Original pipeline parameter: %PipelineParam%" # prints 'foo' echo "Modified pipeline parameter: %env.Job2Param%" # prints 'foo bar'
当此管道作为构建链的一部分时，管道输出参数会共享给下游管道和构建配置。单独设置此类型可让你更好地控制哪些参数可以 Exposed，哪些应保持私密。
请注意，输出参数无法在同一管道内使用。
parameters: PipelineInputParam: foo output-parameters: PipelineOutputParam: bar jobs: Job1: name: Job 1 steps: - type: script script-content: |- # Prints 'foo' echo "Input param: %PipelineInputParam%" # Unresolved reference: no compatible agents echo "Output param: %PipelineOutputParam%"
有关构建链中参数的详情，请参见本节：管道依赖项。

Secret

Secret 是受保护的参数，用于存储敏感数据。您可以像使用常规参数一样引用它们，但其实际值在 TeamCity UI 与构建日志中均被隐藏。

如果您切换到管道的代码视图，您会注意到 secret 值被替换为用于存储这些值的 token 名称。 TeamCity 会自动创建这些 token，以避免通过远程存储的配置文件泄露 secret 数据。

以下代码段展示了可在管道的集成区域中替代密码使用的 secret。尝试暴露该 secret 的命令行脚本会在构建日志中打印“Secret value: *******”行。

jobs:
  Job1:
    name: Job 1
    steps:
      - type: script
        script-content: |-
          echo "Secret value: %registry-password%"
secrets:
  registry-password: credentialsJSON:c57c2732-1d8c-4c11-8724-f275085f4320

  

管道依赖项

本节允许在一个构建链中关联管道和构建配置。

在管道 "B" 的设置中为对象 "A" 添加依赖项时，将创建 "A → B" 链，其中：

对象 A 可以单独运行；
管道 B 启动时会自动触发对象 A。

"A" 可以是经典构建配置，也可以是其他管道。

管道依赖项有以下设置：

依赖于

请选择一个上游配置或管道，使其在当前编辑的管道启动前完成。

执行修订版本同步

指定是否应由 TeamCity 确保通过依赖项关联的两个对象使用相同修订的代码源。

修订同步已启用。：建议用于需要使用相同源状态的设置。例如，在 "A → B" 链中："A" 从修订 1.2 开始，完成后被提升为 "B"。即使最新修订为 1.4，构建 "B" 也会在相同的 1.2 修订上运行。
修订同步已禁用：当构建没有严格的源依赖关系时，请使用此设置（例如，独立的软件包和部署步骤）。在这种情况下，下游构建会使用最新可用的修订。在 "A → B" 链中："A" 从修订 1.2 开始，并在完成后提升到 "B"，但 "B" 会在其最新的 1.4 修订上运行。

请参阅修订同步，了解此设置对整个构建链的影响。

如果有合适的构建，则不要运行新构建

如果启用此选项，当已存在具有相应源修订的另一个正在运行或已完成的构建时，TeamCity 不会运行新的上游构建。请参阅合适的构建，了解 TeamCity 用于确定可重用构建的条件。

在这种情况下，当触发下游构建时，上游构建仍会被放入队列。然后，一旦收集到该链的更改，此上游构建就会从队列中移除，并改为将依赖项链接到合适的已完成构建。

只使用合适的成功构建

新触发的构建只会使用成功完成的合适构建作为依赖。如果最新完成的合适构建失败，它会重新运行。

依赖项失败时、依赖项启动失败或被取消时

这些设置可让您控制在上游构建失败时下游构建是否应运行，以及如果应运行，相同的构建问题是否应出现在其结果中。

运行构建，但添加问题：下游构建会运行，并将问题添加到其中，使其状态变为失败（除非该问题此前已被静音）。
运行构建，但不添加问题：下游构建会运行，且不会添加问题。
将构建标记为启动失败：下游构建不会运行，并会被标记为 "无法启动"。
取消构建：下游构建不会运行，并会被标记为 "已取消"。

下面的代码段演示了如何在代码中设置依赖项。

jobs:
  ...
dependencies:
- ReverseAndOverrideDep_JobParams_UpstreamPipeline:
  reuse: none

    

import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.pipelines.*

object DownsteamPipeline : Pipeline({
    name = "Downsteam pipeline"
        dependencies {
            snapshot(UpstreamPipeline) {
                reuseBuilds = ReuseBuilds.NO
            }
        }
})

    

自动运行流水线

此部分包括允许 TeamCity 在特定条件下自动运行管道的设置。此功能以触发器形式提供。

有新更改时

这些设置会在 TeamCity 检测到仓库中的新更改时触发新的管道运行。在经典 TeamCity 构建配置中，可通过 VCS 触发器实现类似功能。

触发器设置定义哪些更改应启动新的运行。使用分支切换选择稳定的仓库分支。在下面的示例中，只有在更改提交至“production”分支时，TeamCity 才会自动运行管道。

拉取请求切换会将拉取请求分支（例如 GitHub refs/pull/ 分支）包含在可用来源列表中。请注意，仅当管道跟踪这些拉取请求分支时，才能启用该选项（请参见存储库部分）。

按计划

这些设置类似于经典构建配置的计划触发器，可让您定义 TeamCity 运行管道的日期时间模式。

存储库

存储库部分允许您在管道运行期间检出多个仓库。 TeamCity 会从所有已添加的仓库中获取来源，即使未配置任何作业来处理它们。

与管道一起自动创建的初始仓库项称为主仓库。该项不能删除，并包含额外的 YAML 文件存储选择器。

仓库 URL 与来源

核心仓库设置，可让您选择管道应检出的仓库。

主仓库已禁用。

默认分支和分支规范

这些设置定义 TeamCity 应跟踪哪些分支。未被跟踪的分支将被完全忽略：不会向服务器报告更改，您无法对这些分支执行运行等操作。

要详细了解分支规范语法，请参阅以下经典构建配置文章：通用规范语法和默认分支。

拉取请求

启用此设置后，TeamCity 会在主管道页面的分支选择器中显示拉取（合并）请求分支。

您还可以启用 “有新更改时”触发器的相关切换，让 TeamCity 自动构建传入的拉取请求。

配置文件存储

指定管道 YAML 配置的存储位置：在 TeamCity 服务器或源仓库中。这些设置仅适用于主仓库。

配置文件本身可以采用两种格式：YAML（默认）和 Kotlin DSL（请参阅 Pipelines Kotlin DSL.）。根据父项目的版本化设置以及此在仓库中/在服务器上切换开关，行为和可用选项可能会有所不同。

例如，如果项目的版本化设置同步已关闭，则无论位置如何，其管道都会将其设置存储在 YAML 中。否则，当开启项目同步时，管道设置可以采用这些格式中的任一种：已经将其 YAML 设置存储在远程仓库中的现有管道将继续这样做，而新管道以及将设置存储在服务器上的管道会将其 YAML 转换为 .kts 文件。

发布状态到存储库

启用该设置后，TeamCity 会将管道运行状态（运行中、成功、失败）上报至 VCS 托管服务提供商。下图展示了 GitHub 如何呈现此信息。

对于经典构建配置，此功能通过提交状态发布器构建功能提供。

添加更多仓库时，可以选择复用已有连接或 VCS 根目录，或手动输入仓库 URL。

每个单独作业都可以选择其要检出的管道仓库。有关更多信息，请参阅以下文章：作业设置。

功能分支

如果管道将其 YAML 配置存储在仓库中，则可以为各个分支提供自己的工作流：

在设置编辑器中，使用分支选择器切换到某个分支。
编辑作业、步骤、参数或任何其他存储在 YAML 中的设置。
点击保存。 TeamCity 会将更改提交到该分支的 YAML 文件。

没有自己已提交设置的分支会继承默认分支的 YAML 文件中定义的工作流。

受保护的分支

如果所选分支受保护，TeamCity 可能无法直接提交您的更改。在这种情况下，点击保存会提示您改为选择其他分支进行保存。

或者，切换到设置编辑器的代码视图，复制生成的 YAML，并按照团队的分支保护规则手动将其提交到受保护的分支。

集成

pipeline 和作业设置面板都包含一个集成部分，用于连接私有 Docker 和 NPM 注册表。

在 pipeline 设置中，您可以管理作业可用集成的完整列表。
在作业设置中，开关允许您选择该作业应自动登录哪些注册表，从而确保构建步骤能够访问所需数据。

YAML

直接添加到管道的集成现在确实会将其设置公开给 YAML。在 YAML 中可见的集成唯一部分，是为每个特定作业启用的集成 ID 列表。

jobs:
  Job1:
    name: Job 1
    steps:
      - type: script
        name: Run in ECR container
        script-content: |-
          echo "Successfully authenticated and running inside ECR image"
        docker-image: 12345.dkr.ecr.eu-west-1.amazonaws.com/johndoe/my-image:latest
    integrations:
      - AmazonDocker: PROJECT_EXT_112
      - Docker: PROJECT_EXT_30

   

继承的集成

如果某个项目中已有 Docker 或 NPM 连接，则该 pipeline 会在其“集成”部分下显示该连接。

这些继承的集成无法直接通过 pipelines 设置面板编辑，您需要在项目设置中修改其源连接。

Amazon ECR

目前，管道和作业仅支持继承的 Amazon ECR 连接 — 不能通过管道设置侧边栏或 YAML 添加这些连接。

父项目拥有的所有 Amazon ECR 连接都会显示在集成部分下。各个作业会显示开关，用于指定该作业是否应使用此特定连接。

在构建配置中

传统 TeamCity 构建配置通过“连接 + 构建功能”组合支持此功能：

Docker 注册表连接构建功能使用 Docker Registry 和 Amazon ECR 连接。
NPM Registry 构建功能使用相应连接。