配置链依赖项配置

一个构建链通过在指向上游对象的下游对象中声明依赖项来组装。构建配置和流水线的可用设置相同 — 只有 UI 和代码表示不同。

快照依赖项

快照依赖项将链中的两个构建配置连接起来。术语 "快照" 指源修订同步：上游和下游构建共享同一个代码快照，这是使链有意义的密钥保证。

要向构建配置添加快照依赖项：

打开配置设置，并导航到 依赖项设置选项卡。
点击添加新的快照依赖项并选择上游配置。

// "Build → Test → Deploy" chain.
// Upstream configurations have no dependencies — add them only to downstream ones.

object Test : BuildType({
    name = "Test"
    dependencies {
        snapshot(Build) {}   // Test runs after Build
    }
})

object Deploy : BuildType({
    name = "Deploy"
    dependencies {
        snapshot(Test) {}    // Deploy runs after Test
    }
})

  

流水线依赖项

流水线依赖项将流水线链接到其他流水线或经典构建配置。

要添加流水线依赖项：

点击流水线画布区域中的任意位置（任何作业之外）以打开流水线级别设置。
点击添加，位于流水线依赖项部分。
从依赖于列表中选择上游流水线或构建配置。

# Simple form — uses default settings
dependencies:
  - UpstreamPipeline

# Extended form — override specific settings
dependencies:
  - UpstreamPipeline:
      reuse: none
      enforce-revisions-synchronisation: true
      on-failed-dependency: run-add-problem
      on-incomplete-dependency: cancel

    

object DownstreamPipeline : Pipeline({
    name = "Downstream Pipeline"
    dependencies {
        snapshot(UpstreamPipeline) {
            reuseBuilds = ReuseBuilds.NO
        }
    }
})

    

依赖项设置

以下设置同时适用于快照依赖项和流水线依赖项。

依赖于

选择必须先完成的上游配置或流水线，然后此对象才能启动。

执行修订版本同步

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

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

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

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

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

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

只使用合适的成功构建

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

在同一代理上运行构建

启用后，下游构建会在同一链中运行过上游构建的同一构建代理上运行。当上游构建修改系统状态 — 已安装的工具、环境变量或本地文件 — 且下游构建依赖这些状态时，请使用此设置。

依赖项失败时 / 依赖项启动失败或已取消时

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

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

构建复用

每次链触发器触发时运行每个上游构建通常很浪费 — 如果已存在匹配的构建，TeamCity 可以复用它。这使链不仅仅是固定序列：TeamCity 不会盲目重新运行所有内容，而是决定要执行哪些上游构建，以及哪些用早先的结果替代。

复用由如果有合适的构建，则不要运行新构建依赖项选项控制。启用后，TeamCity 会查找一个适用的构建来使用，而不是启动新的构建。

适用的构建

适用构建是 TeamCity 可复用来替代已排队上游构建的现有构建。启用构建复用后，TeamCity 会搜索适用的构建，如果找到，则将依赖项链接到该构建，并删除冗余的已排队构建。

当满足以下所有条件时，构建被视为合适：

它属于相同分支或默认分支。
它使用与已排队链相同的源快照（相同修订；如果 VCS 根不同，则为同一时刻获取的修订）。
如果启用了只使用合适的成功构建选项，则它是成功的。
它是常规的非个人构建，没有自定义参数。
自该构建运行以来，构建配置设置未发生变化。
它自己的所有依赖项构建也都适用。
并非 "挂起" 构建。

如果没有构建满足所有条件，TeamCity 会改为运行新的上游构建。

禁用构建复用的 VCS 设置

某些 VCS 根配置会使 TeamCity 无法可靠地计算修订，从而完全禁用构建复用。这些是：

Subversion — "检出，但忽略更改" 模式。
CVS — "按标记检出" 模式。
Perforce — "Stream" 或 "Client" 连接设置，或指定为 "要检出的标签/修订" 的标签。
StarTeam — 检出模式设置为 "查看标签" 或 "提升日期"。

并行测试和构建复用

始终运行新构建行为（快照依赖如果有合适的构建，则不要运行新构建设置已禁用）仅影响主配置构建。当使用并行测试功能时，动态生成的虚拟构建配置可能仍会重用其先前的结果。如果未检测到新的存储库提交，则只有先前失败的测试批次会运行新的构建，而成功的批次会被重用。

在下图中，“Composite Conf”配置依赖于“Maven App”配置。后者以两个并行批次运行其测试。请注意，主“Maven app”构建 #18 被重新触发，而动态生成的“Maven app 1”配置重用了其先前成功的构建（#12）。

您可以强制 TeamCity 重新运行所有虚拟配置构建。在这种情况下，即使未发现新的存储库提交，每个单独的测试批次也会重新运行。

为此，请将 teamcity.internal.splitBuild.dependency.takeStartedBuildWithSameRevisions=false 参数添加到具有并行测试功能的配置中。

要将此行为应用于服务器上的所有配置，请将此参数添加到内部属性列表中。

修订同步

默认情况下，链中的每个成员都在相同的源快照上运行。在特定依赖项上禁用执行修订版本同步会将链拆分为独立的修订组，因此可以跨该链接将构建提升到较新的修订。

典型用例是部署：使用最新部署脚本部署较早的、已验证的构建。

设想一个 "D → C → B → A" 链，其中 D 进行编译，C 运行集成测试，B 运行系统测试，A 执行部署。 B 的依赖项上的同步为已禁用，但已为 A 和 C 启用：

D 和 C 已同步 — 两者都在修订 1 上运行。
B 和 A 已同步 — 两者都在修订 3 上运行。
C → B 链接已解除同步，因此两个组可以使用不同的修订。

这样可以将较早的编译结果（D，修订 1）直接提升到 B，跳过 C，同时 B 和 A 仍在最新修订 3 上运行。

需要遵循的一条规则：如果其下游构建也通过不同路径与另一个上游构建同步，则不要取消同步该链接。这会产生相互矛盾的修订要求。两种安全的拓扑结构是：在复刻的一整侧禁用同步……

...或在重新汇合前在两条分支上都禁用同步。

2026年 9月 11日