创建和编辑构建配置

构建配置和管道代表实际的 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 中创建构建配置

要将构建配置添加到 TeamCity 项目中，请使用侧边栏中的 + 按钮...

……或从项目设置的常规选项卡中点击创建构建配置。

可用选项

构建配置可以属于两大类之一：一种是构建、测试或部署存储在 VCS 中的项目的配置，另一种则不需要远程仓库（例如，它可能使用第三方 REST API 下载并处理数据）。

用于检查远程仓库的配置可以通过 TeamCity 连接或 VCS 根来创建。

所有可用选项将在设置您的构建页面的相应下拉菜单中显示。

使用 TeamCity 连接

TeamCity 连接存储访问外部资源所需的全部信息：VCS 托管、云数据存储、Docker 注册表、机密保管库等。使用连接是构建源码最便捷的方式：仅需配置一次，之后在添加新的构建配置或流水线时，只需从列表中选择所需仓库。

上述图示展示了现有连接的列表：GitLab 连接、GitHub 连接、若干 Azure 连接等。如果构建配置所属的项目没有任何一个拥有 VCS 连接，您唯一的选项是通过连接新仓库菜单项创建一个新的连接。

使用仓库 URL

此选项允许您使用 Git、Subversion、Mercurial、TFS 或 Perforce 仓库（depot）URL 一次性创建构建配置。您可以使用任何 URL 类型：

常规存储库网页链接： https://github.com/Johndoe/my-sample-app
HTTPS 克隆 URL： https://github.com/Johndoe/my-sample-app.git
SSH 克隆 URL： git@github.com:Johndoe/my-sample-app.git

要开始构建远程存储库，请按照以下步骤操作。

在设置您的构建页面中，选择来自任意 Git URL 选项。
选择身份验证类型。
SSH key
如果存储库 URL 是 SSH 克隆 URL，则可用。点击上传 SSH 密钥以添加私钥，该私钥将保存在父项目中（父项目设置| SSH 密钥），并在配置其他项目时出现在下拉菜单中。
了解更多： SSH 密钥管理
HTTPS
此选项适用于 HTTP(s) 克隆 URL，提供三种身份验证选项：
- Token — 在 VCS 端生成个人访问令牌（PAT），并粘贴至此处。您也可以使用 TeamCity 管理可刷新访问令牌页面来生成令牌。
- 密码 — 输入常规的用户名/密码凭据。
- 匿名 — 适用于公共仓库。仅当您不打算使用写入权限（例如，将 TeamCity 构建状态回传至 VCS）时，才应使用此选项。
设置基本配置选项。
- 名称和（可选）描述 — 显示在 TeamCity UI 中的公共文本。
- 默认分支 — 将成为 TeamCity 中默认分支的完整分支名称（例如， refs/heads/main）。有关更多信息，请参阅以下文章：默认分支。
  默认情况下，TeamCity 跟踪所有分支（refs/heads/*）。您可以稍后通过编辑附加到此配置的 VCS 根的分支规范来更改此行为。请参阅以下主题以了解更多信息：使用功能分支。
- 在有新更改时启动构建 — 启用后，会添加一个 VCS 触发器，每当 TeamCity 检测到新提交时启动新构建。
- 构建配置类型 — 允许您根据用途选择配置类型。请参阅本文以了解复合和部署配置的独特功能。
点击创建。 TeamCity 将引导您进入详细的配置设置页面，在此页面您可以添加构建步骤、编辑监视的分支列表、启用其他构建功能等。

使用 VCS 根目录

每个处理远程仓库中源码的构建配置都依赖于 VCS root（VCS 根）。该对象存储访问单个仓库所需的连接设置和高级设置：监视的分支列表、自动轮询间隔、子模块检出策略等。

如果您已有用于构建、测试或部署所需仓库的构建配置或流水线，则可以重用该配置或流水线的 VCS 根。为此，请使用以下任一方法：

创建新配置 — 在设置您的构建页面中选择来自现有根目录选项。
编辑现有配置 — 导航至构建配置设置 | 版本控制并点击附加 VCS 根。

重用现有 VCS 根可以节省设置所需授权和分支设置的时间，并避免创建重复的根。

无仓库的配置

此配置类型在运行时不会检出任何远程仓库。例如，其步骤仅会执行预定义的脚本并发送 HTTP 请求。

您可以通过两种方式创建新的 "unbound: 配置：

在设置您的构建页面上，选择无仓库。
在经典 UI 中，打开新建构建配置页面并点击手动图块。

VCS 根控制 VCS 提供程序连接和仓库检出。因此，您可以通过分离其 VCS 根，使任何构建配置变为非绑定状态。反之，将 VCS 根附加到没有仓库的配置将允许其检出远程源。这两项操作都可以在构建配置设置的版本控制部分中执行。

包含多个仓库的配置

配置通过其附加的 VCS 根来决定要检出的仓库以及要跟踪的分支。一个配置可以拥有任意数量的根，从无到多个。

通常，一个配置使用单个仓库，因此具有一个 VCS 根。如果需要构建完全独立的项目，最佳做法是创建单独的配置，并在必要时将它们链接在构建链中。但是，当多个仓库相关（例如核心产品及其插件）时，您可以将多个 VCS 根附加到同一个配置中以共同构建。为此，使用本文中提到的任意方法创建配置，然后转到其设置的版本控制部分。在此，您可以创建更多 VCS 根以定位所需仓库。

下面的 Kotlin DSL 代码段展示了一个拥有两个已附加根的配置。

package _Self.buildTypes

import jetbrains.buildServer.configs.kotlin.*

object MultiRepoBuild : BuildType({
    name = "Multi-repo build"

    vcs {
        root(MavenRepoRoot, "+:. => MavenRepo")
        root(GradleRepoRoot, "+:. => GradleRepo")
    }
})

   

所有 VCS 根会将源下载到同一个检出目录中。为避免文件冲突并保持文件夹有序，最佳做法是使用根检出规则将每个仓库的源下载到不同的子目录中。例如，上方的代码段将源放置在默认检出目录下的 "MavenRepo" 和 "GradleRepo" 文件夹中。

示例：创建基于连接的配置

在本示例中，我们将添加一个到 GitHub 的连接，并使用它创建一个新的构建配置。

TeamCity 支持两种 GitHub 身份验证方法：OAuth 2.0 和 GitHub 应用。这两种类型都只需最少的自定义，设置时间不到一分钟。要详细了解这两种连接类型及其他 VCS 提供程序连接，请参阅本文：配置连接。

您可以通过两种方式创建基于连接的配置：在项目设置下创建连接并在设置您的构建页面选择，或直接在此页面完成全部操作。下面的选项卡展示了两种方法。

使用 TeamCity UI 将构建配置添加到所需项目中。
从下拉菜单中选择连接新仓库。
展开 GitHub 图块并选择 GitHub.com。
按照 TeamCity 指引导航至 GitHub 的 "Developer Settings" 页面，并创建一个新应用程序。
在 GitHub 应用程序页面中点击生成新的客户端密钥，然后将此 secret 和客户端 ID 粘贴到 TeamCity 对应的连接属性中。
在 GitHub 上安装应用程序后，您可以在设置您的构建页面下拉菜单中选择新的连接。请注意，首次使用时，您需要点击授权 <Username> 以使用您的新连接登录 GitHub。
TeamCity 将显示通过底层连接可访问的存储库列表。使用搜索面板找到所需的存储库，然后点击以继续。
设置基本配置选项并点击创建完成操作。

第 1 步：创建连接

打开应拥有新 GitHub 连接的项目的设置。如果希望将来该连接对服务器创建的任何项目可用，请修改根目录项目。
导航到连接选项卡并点击添加连接。
选择 GitHub 应用作为连接类型并点击创建应用。
TeamCity 将重定向您到 GitHub 以批准该应用，选择其安装位置（个人账户或组织），并可选地限制其存储库访问。您可以随时通过 GitHub 设置 | 开发者设置 | GitHub 应用查看和编辑 TeamCity 配置的应用，或在 GitHub 设置 | 应用页面上卸载它。
安装应用后，您将返回到 TeamCity，所有连接设置（应用 ID、客户端 ID、客户端密钥等）的值将已填充。点击测试连接以验证设置，然后点击保存以完成设置。

第 2 步：创建构建配置

使用 TeamCity UI 将构建配置添加到所需项目中。
从列表中选择新的连接。如果这是第一次使用该连接，您可能需要登录。
TeamCity 将显示通过底层连接可访问的存储库列表。使用搜索面板找到所需的存储库，然后点击以继续。
设置基本配置选项并点击创建完成操作。

在 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年 12月 17日