创建和编辑构建配置

构建配置和管道代表实际的 CI/CD 流程。构建配置存储了一系列构建步骤（在构建运行期间执行的基本操作）以及执行这些步骤所需的设置。这些设置包括：

参数，允许您快速更改配置行为；
触发器，允许 TeamCity 在满足特定条件时自动启动新构建；
构建功能，扩展配置的功能；
代理要求，允许您在特定的构建代理上运行配置构建；
至关重要

建议为每个构建序列（即在专用环境中执行特定任务）创建单独的构建配置或管道。这允许适当的功能正常运行，如新问题/失败测试的检测，首次失败/修复测试的状态，自动删除的调查等等。

构建配置与管道

在我们深入创建配置之前，了解构建配置和管道之间的区别以及何时使用它们非常重要。请注意，一旦创建，您无法将构建配置转换为管道或作业，反之亦然。

父项目

构建配置和管道都归 TeamCity 项目所有。每个项目可以拥有无限数量的配置和管道。

子项目

一个构建直接拥有其构建步骤。
一个管道拥有作业，而作业又拥有常规的构建步骤。

支持的 VCS 类型

经典的 TeamCity 构建配置支持 Git、Subversion、Mercurial、TFS 和 Perforce，并与主要的 VCS 提供商（如 GitHub、GitLab、Bitbucket、Azure 等）集成。
TeamCity 管道提供与 GitHub、GitLab 和 Bitbucket Cloud 的内置集成。其他 Git 仓库可以通过直接 URL 连接。目前不支持 Subversion、Mercurial、TFS 和 Perforce。

执行模式

管道总是从头到尾运行，执行所有作业，除非因编译失败或连接问题等错误中断。
构建配置支持条件步骤执行。例如，您可以添加一个仅在前一步失败时运行的步骤。

依赖

目前，管道仅支持同一管道内作业之间的依赖关系，无法链接成更大的序列。
构建配置可以在不同的 TeamCity 项目之间形成构建链。

配置即代码

管道和构建配置都可以将其设置存储为代码，与您的项目源代码一起存放。这两种实体都支持分支设置，这意味着每个仓库分支可以有自己的配置文件。

构建配置将其设置存储为 XML 或 Kotlin DSL 格式。您无法从 TeamCity UI 编辑这些文件。
管道将其设置存储为 YAML，可以直接在 TeamCity 中编辑。

Kotlin DSL 支持计划在未来的管道版本中提供。然而，目前没有为构建配置添加 YAML 支持的计划。

技术所限

构建配置是 TeamCity 的核心组件，提供了广泛的功能和自定义选项。
在 TeamCity 2025.07 引入的管道专注于提供设计 CI/CD 工作流的最直观方式。然而，目前它们缺少了构建配置中的一些功能。例如，它们不支持大多数构建步骤，也没有额外的构建功能。

总之，尽管管道和构建配置同样属于项目，但它们满足了不同的需求。管道非常适合较小项目中较为简单的 CI/CD 工作流（通常最多 10-15 个构建）。请改用构建配置，如果：

您的项目涉及超过 10-15 个顺序构建的复杂工作流。
您是一位经验丰富的用户，需要管道尚未提供的高级功能（例如构建审批）。
您需要对哪些构建链配置运行、何时运行以及如何运行进行精细控制。

在 TeamCity UI 中创建构建配置

创建新的构建配置与创建项目有许多相似之处：两者都可以利用连接并依赖 VCS 根来访问远程仓库。

新项目

当您从仓库 URL或通过已配置的连接创建一个新的 TeamCity 项目时，TeamCity 将引导您设置项目及其构建配置。请参见上方链接以获取更多详细信息。

将配置添加到现有项目

如果已存在父项目，您可以按以下步骤添加其子配置：

在侧边栏中使用 + 按钮……
……或从项目设置的常规选项卡中点击创建构建配置。
系统会为您呈现与创建项目相同的选项集：
- 从仓库 URL——使用仓库链接添加新配置。请参阅此链接以了解更多信息。
- 从已配置的连接——如果此项目或其任何父项目具有 VCS 提供商连接，则此选项可用。比第一个选项更快捷，因为身份验证设置继承自底层连接。请参阅此链接以了解更多信息。
- 手动——创建一个完全空白的构建配置，不针对任何远程仓库。此选项允许您选择附加到该配置的模板。
如果您创建了一个空白的构建配置（使用手动选项），您需要附加一个现有的 VCS 根或创建一个新的，以检出远程仓库。一个配置可以包括多个 VCS 根，以处理来自相同或不同提供商的仓库。
附加或创建 VCS 根
1. 前往 Administration 并点击您想要配置的项目。
2. 从项目的 常规设置页面，点击相关的构建，位于 构建配置 下面
3. 从侧边栏中选择 Version Control Settings。
4. 点击 附加 VCS 根。
5. 如果至少有一个现有的 VCS 根可用，TeamCity 提供了以下操作的选择：
  - 关联现有的 VCS 根目录 — 选择要关联的 VCS 根目录，然后完成 更新检出规则表单。
  - 创建新的 VCS 根 — 遵循配置 VCS 根中的指南，配置新的 VCS 根。
  如果没有现有的 VCS 根可用，TeamCity 将直接跳到 创建新的 VCS 根 页面。
请参阅以下文章以获取更多信息：
- 配置 VCS 设置
- 配置 VCS 根目录

在 Kotlin DSL 中创建新项目

以下 Kotlin 代码创建了一个新构建配置，利用目标 VCS 根与 VCS 托管提供商交互：

object RunTests: BuildType({
  id("RunTests")
  name = "Run unit tests"
  description = "Runs all unit tests of the project"

  vcs {
    root(MyProjectVCSRoot)
  }

  steps {
    // Add build steps
  }

  triggers {
    // Add triggers
  }
})

  

请参阅这些文章以获取更多信息：

通过 REST API 创建构建配置

以下请求创建了一个新的空 TeamCity 构建配置，由特定的父项目所有。

export TEAMCITY_SERVER_URL="<Your TeamCity Server URL>"

curl --location $TEAMCITY_SERVER_URL'/app/rest/projects/<parent_project_locator>/buildTypes' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <Your TeamCity Access Token>' \
--data '{
    "name": "New Build Configuration from REST"
}'

  

请参阅以下文章以获取更多信息：

构建配置模板

模板允许您快速生成具有相同设置的多个配置。创建配置后，您可以覆盖其设置。

您可以手动创建构建配置模板或从现有配置中提取模板。

手动创建模板

创建模板与通过手动瓦片创建构建配置相同。

打开项目设置并导航到常规设置选项卡。
向下滚动到构建配置模板部分并点击创建模板。
输入模板名称和描述，并点击创建。
指定应出现在从此模板生成的每个配置中的设置：
- 构建步骤
- 构建参数
- 触发器等。

从配置中提取模板

如果您已经有一个想用作参考的构建配置，可以从中提取一个模板。

打开构建配置设置。
打开右上角的操作菜单，并点击提取模板...。
输入配置名称，然后点击提取。您可以保留模板 ID 为其自动生成的值。
源配置将是第一个使用新模板的配置。若要保持独立性，请点击分离。否则，对模板的任何更改将适用于此模板及所有基于它的其他配置。

从模板创建构建配置

您可以通过两种方式创建模板化的构建配置：从模板设置页面，或通过创建常规配置并选择应使用的模板。

选项 #1：

打开项目设置并导航到常规设置选项卡。
向下滚动到构建配置模板部分，并点击所需的模板。
在右上角调用操作菜单，并点击从此模板创建构建配置...。

指定新配置所需的设置。不要点击手动以外的任何磁贴；否则，您将创建一个未使用所选模板的新配置。

选项 #2：

打开项目设置并导航到常规设置选项卡。
点击创建构建配置，位于构建配置部分下方。
点击手动磁贴，并在基于模板下拉菜单中选择所需的模板。如果此项目或其任何父项目拥有至少一个构建配置模板，则此菜单可用。

选项 #2 在构建配置模板部分未显示所需模板（因为它由另一个（子）项目拥有）时很有帮助。

重新排列构建配置

您可以在项目概览页面上查看项目的所有构建配置。默认情况下，它们是按字母顺序列出的，但管理员可以自定义这个顺序。

构建配置设置

构建配置设置包括：

一般设置
版本控制设置，定义了如何从 VCS 中检索源代码，检出到何处等等
构建步骤，即按顺序运行的动作：例如，运行 msbuild，一个脚本，或单位测试
触发器，这些是定义何时启动新构建的规则
失败条件规定了何时会将构建标记为失败
附加的构建功能
依赖项:
- 对于快照依赖，TeamCity 会在它们所依赖的构建开始时运行所有依赖的构建，这些源是在构建开始时获取的。
- 对于工件依赖，在构建开始之前，所有这个构建依赖的工件都将被下载并放置在它们配置的目标位置，然后将由构建使用。
参数允许共享设置
代理要求指定某个构建配置是否可以在特定的构建代理上运行。

编辑构建配置的权限

虽然只有具有项目管理员权限的用户才能更改项目和构建配置设置，但是对源代码做出贡献的参与者也有许多方式可以影响构建设置和环境。

默认的 Project Developer 角色授予用户两项权限：

自定义构建参数允许更改构建配置参数的值，从而可能影响源代码的执行方式。
使用自定义补丁更改构建源代码允许根据用户的本地源文件运行自定义构建，而这些文件尚未提交至存储库。

此外，所有编写源代码或/和可以在其中存储项目设置的 Kotlin DSL 仓库中写入的用户，都可能在共享构建代理上执行他们的任意代码。

我们建议在授予用户上述权限或向项目仓库写入访问权限时，考虑这个方面。如果需要，您可以调整分配给每个权限的集合。

在构建配置设置中的操作

使用位于设置屏幕右上角的操作菜单以：

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