Pull Request

拉取请求构建功能将 TeamCity 与 GitHub、 Bitbucket 服务器、 Bitbucket Cloud、 GitLab、 Azure DevOps 和 JetBrains Space 仓库中的拉取（合并）请求集成。

常见信息

将 Pull Requests 功能添加到构建配置允许您：

在构建配置的概览页面上查看拉取请求分支及其待处理的更改。
在概述选项卡上查看构建结果页面的拉取请求详细信息。
对于草稿拉取请求，图标显示为灰色，并且草稿状态显示在拉取请求编号之前：
使用作者、目标分支和源分支筛选器来筛选要监控的拉取请求。
请注意， Pull Request 构建功能的分支过滤器仅接受完全限定的 VCS 分支名称，而不管这些分支在 TeamCity UI 中如何显示。
例如，如果用户通过执行 gh pr create --base source-branch --head master --assignee "@johndoe" GitHub CLI 命令创建了一个新的 pull request，可以使用 refs/heads/source-branch 和 / 或 refs/heads/master 名称来指向 Pull Requests 功能的相关目标 / 源分支。省略 refs/heads/ 并使用缩短的逻辑分支名称（[+|-]：source-branch、 [+|-]:master、 [+|-]：pull/10 ）将导致过滤器出现错误，无法定位到所需的分支。
设置一种工作流程，让开发者在本地分支中工作，只有在这些更改作为拉取（合并）请求发送后，TeamCity 才会构建这些更改 — 请参见下面的与 VCS 根的交互。

拉取请求功能不会自动触发针对拉取（合并）请求分支的新构建。要在拉取请求分支中的更改合并到主代码库之前进行评估，请添加一个以所需分支为目标的 VCS 触发器（例如，GitHub 使用 refs/pull/N/head）。在 TeamCity UI 中创建的新构建配置已包含一个带有 +:* 规范的触发器，这使 TeamCity 能够构建来自拉取（合并）请求分支的更改。

如果您的构建配置针对的是公共仓库，其中不受信任的用户可以推送提交或创建拉取（合并）请求，那么构建这些更改意味着 TeamCity 可以执行其中引入的恶意代码。例如，TeamCity 可能处理来自源代码的有害的服务消息，或者应用来自修改了的 .teamcity 文件夹文件的改变后的项目设置。

为防止这种情况，请不要以会让包含未验证拉取（合并）请求更改的构建自动启动的方式配置 VCS 触发器和拉取请求构建功能。请改为在检查并验证传入更改后手动启动新构建，或设置不受信任的构建以要求对外部拉取请求进行额外审查。

请查看此部分以获取有关可以修改仓库代码的用户可能导致的潜在损害的更多信息：安全说明。

如果项目以 GitHub 或 GitLab 仓库为目标，可以进一步让 TeamCity 构建拉取请求分支，并合并生成成功构建的那些请求。为此，请添加自动合并构建功能，并将其与 Pull Request 一起使用。

与 VCS 根的交互

Pull Requests” 功能扩展了当前构建配置中附加的 VCS roots 原始分支规格。因此，VCS 根的分支规范不得包含与拉取请求分支匹配的模式，以避免产生歧义和意外行为。

如果构建配置应构建仅剩拉取请求，请清除其父 VCS 根的分支规范：

object MyRepoRoot : GitVcsRoot({
    name = "MyRoot"
    url = "https://github.com/username/reponame"
    branch = "refs/heads/main"
    // Note the "branchSpec = ..." parameter is missing
})

  

如果此 VCS 根与其他配置共享，请改用配置分支筛选器，以便仅保留拉取请求分支可用：

project {
    vcsRoot(SharedVcsRoot)
    buildType(PullRequestsConfig)
}

// VCS root with a branch spec
object SharedVcsRoot : GitVcsRoot({
    name = "shared-vcs-root"
    branch = "main"
    branchSpec = """
        refs/heads/main
        refs/heads/sandbox
        refs/heads/dev-*
    """.trimIndent()
})

// Build configuration that nullifies root's branch spec
object PullRequestsConfig : BuildType({
    name = "Pull Requests Config"

    vcs {
        root(SharedVcsRoot)

        branchFilter = """
            -:*
            +:refs/pull/*   
        """.trimIndent()
        /* exclude all branches and re-add pull request ones */
    }
})

  

下面的示例展示了如何设置 TeamCity 项目，使根分支规范和拉取请求功能相互配合，以实现以下工作流程：

TeamCity 仅跟踪 主要、 生产 和 沙箱 分支，以及所有以 "release-" 开头的分支（例如 release-2077.02）。
开发者可以创建本地分支并在其中工作，而不会暴露给 TeamCity。
当开发者准备发布更改时，会创建一个请求，将提交从个人（未跟踪）分支合并到核心（已跟踪）分支。这会产生一个新的拉取分支（例如 GitHub 上的 refs/pull/54）。拉取请求功能会检测到此新分支，从而可以在合并之前在 TeamCity 中构建并测试这些更改。
借助该功能的按作者过滤设置，TeamCity 会忽略由未经授权（外部）用户创建的类似 refs/pull/<Int> 分支。

project {
    vcsRoot(MyRepoRoot)
    buildType(Build)
}

object Build : BuildType({
    name = "Build"
    vcs { root(MyRepoRoot) }

    // ...

    features {
        pullRequests {
            vcsRootExtId = "${MyRepoRoot.id}"
            provider = github {
                authType = vcsRoot()
                filterAuthorRole = PullRequests.GitHubRoleFilter.MEMBER
            }
        }
    }
})

object MyRepoRoot : GitVcsRoot({
    name = "MyRoot"
    url = "https://github.com/username/reponame"
    branch = "refs/heads/main"
    branchSpec = """
        refs/heads/main
        refs/heads/production
        refs/heads/sandbox
        refs/heads/release-*
    """.trimIndent()
})

  

针对 VCS 的特定设置

GitHub 拉取请求

这个功能支持 GitHub 和 GitHub Enterprise。它仅监控在 refs/pull/*/head 分支上的构建。

以下参数适用于 GitHub 托管类型：

身份验证类型

使用 VCS 根证书 — 如果 VCS 根使用 HTTP(S) 获取 URL，TeamCity 会尝试从 VCS 根设置中提取用户名/密码凭据或个人访问令牌/x-oauth-basic。如果 VCS 根使用匿名身份验证或 SSH，此选项不起作用。对于 GitHub Enterprise 仓库，只有个人访问令牌/x-oauth-basic 对才有效。
访问令牌 — 如果已配置到 GitHub 的 OAuth 连接，请点击魔杖按钮，让 TeamCity 自动检索相应的访问令牌。
否则，如果手动插入在 GitHub 侧发放的令牌，请确保其具有以下权限或作用域：
- 经典 GitHub 令牌： public_repo 用于公共仓库， 仓库 用于私有仓库。另请参阅： OAuth 应用的作用域。
- 细粒度令牌：添加具有 "Read-only" 访问类型的 拉取请求 权限。该权限仅可添加到“所有仓库”或“仅选择的仓库”访问类型的令牌。另请参阅：精细化个人访问令牌所需权限。
GitHub 应用程序访问令牌 — 通过 GitHub 应用签发的非个人短期令牌。仅当 VCS Root（VCS 根）设置指向使用 GitHub 应用连接配置的特定 VCS 根时可用。

发现模式

确定 TeamCity 如何识别拉取请求：

按分支规范引用（默认）— TeamCity 通过拉取请求实际的 refs/pull/N/head 分支来识别它们。
按源分支名称 — 请求通过其源分支来识别。启用模式具有以下效果：
- 来自复刻的拉取请求会被忽略。
- 来自同一源分支的不同拉取请求会聚合为一个，并可在同一个构建中处理。
- 在 TeamCity UI 中会显示源分支名称（而默认模式下显示 pull/N 名称）。
- 附带效果是，如果两个配置链接成构建链，TeamCity 会更准确地同步发往不同仓库的拉取请求。例如，在默认模式下，如果上游配置处理来自 pull/10 分支的更改，则下游构建会针对同一分支运行。鉴于每个仓库都有自己唯一的拉取请求计数器，此链可能会构建不相关的更改。如果启用了按源分支名称模式，TeamCity 会识别出一个仓库的 pull/10 分支中的更改对应于另一个仓库的 pull/54 分支，因为二者都源自同一个 沙箱 分支。

请注意，切换此模式会改变 TeamCity 识别拉取请求的方式，这可能导致新拉取请求大量涌入（如果配置了自动触发器，还会导致排队构建大量涌入）。这是构建量的一次性峰值，待所有新发现的拉取请求都处理完后即可恢复。

由作者

筛选器按作者筛选 TeamCity 监控的拉取请求。仅适用于公共仓库。

同一组织的成员 — 仅检测由同一组织的成员提交的拉取请求。
成员和外部合作者 — 仅检测由同一组织的成员和外部协作者提交的拉取请求。
每个人 — 检测所有拉取请求。请注意，此选项可能允许任意用户在构建代理上执行恶意代码。

按源分支

将监控的拉取请求限制为与此分支筛选器匹配的源分支。留空则不应用筛选器。

按目标分支

将监控的拉取请求限制为与此分支筛选器匹配的目标分支。留空则不应用筛选器。

忽略草稿

默认情况下，拉取请求构建功能会加载 GitHub 草稿拉取请求信息并对其运行构建 — 构建页面会在拉取请求编号旁显示灰色图标和草稿状态。

勾选此框以忽略 GitHub 的草稿拉取请求。在状态发生变化之前，TeamCity 不会加载草稿拉取请求信息。

服务器 URL

用于连接的 GitHub URL。如果留空，URL 将从 VCS 根获取 URL 中提取。

Bitbucket Server / Data Center 拉取请求

以下参数适用于 Bitbucket Server/Data Center 托管类型：

身份验证类型

使用 VCS 根证书 — 如果 VCS 根使用 HTTP(S) 获取 URL，TeamCity 会尝试从 VCS 根设置中提取用户名/密码凭据。如果 VCS 根使用 SSH 获取 URL 或采用匿名身份验证，此选项不起作用。
用户名/密码 — 指定用于连接到 Bitbucket 服务器/Data Center 的用户名和密码。可以提交访问令牌而不是密码；该令牌应具有项目和仓库的读取权限。
可刷新访问令牌是由 TeamCity 通过现有的 OAuth 连接从所需的 VCS 提供商获取的短期令牌（与用户在 VCS 托管端手动颁发的静态 PAT 令牌不同）。有关生成和使用可刷新令牌的更多信息，请参阅以下文章：管理可刷新访问令牌。

按源分支

将监控的拉取请求限制为与此分支筛选器匹配的源分支。留空则不应用筛选器。

按目标分支

将监控的拉取请求限制为与此分支筛选器匹配的目标分支。留空则不应用筛选器。

服务器 URL

用于连接的 Bitbucket URL。如果留空，URL 将从 VCS 根获取 URL 中提取。

使用拉取请求分支

仅用于向后兼容。启用对官方不支持的 Bitbucket 拉取请求分支（pull-requests/* ）而非源分支的检测。

请注意：在切换后的最后一个小时内提交的更改可能会触发新的构建。

Bitbucket Cloud 拉取请求

由于 Bitbucket Cloud 不会为拉取请求创建专用分支，此构建功能会直接监控源仓库中的源分支（不支持复刻）。如果在构建启动时有多个拉取请求从同一源分支提交，TeamCity 会在构建结果中显示所有这些请求。但是，只有来自符合筛选器条件的开放 PR 的提交才会显示为构建的更改。

请注意，VCS 根的分支规范不得包含匹配拉取请求分支的模式。

以下参数可用于 Bitbucket Cloud 托管类型：

身份验证类型

使用 VCS 根证书 — 如果 VCS 根使用 HTTP(S) 获取 URL，TeamCity 会尝试从 VCS 根设置中提取用户名/密码凭据。如果 VCS 根使用 SSH 获取 URL 或采用匿名身份验证，此选项不起作用。
用户名/密码 — 指定用于连接到 Bitbucket Cloud 的用户名和密码。我们建议您使用带有 Pull Requests | Read 权限范围的 app 密码。
可刷新访问令牌是由 TeamCity 通过现有的 OAuth 连接从所需的 VCS 提供商获取的短期令牌（与用户在 VCS 托管端手动颁发的静态 PAT 令牌不同）。有关生成和使用可刷新令牌的更多信息，请参阅以下文章：管理可刷新访问令牌。
永久访问令牌 — 输入 Bitbucket 仓库访问令牌、项目访问令牌或工作区访问令牌，用于对仓库、工作区或项目进行长期访问。令牌必须具有拉取请求 | 读取作用域。

按目标分支

将监控的拉取请求限制为与此分支筛选器匹配的分支。留空则不应用筛选器。

GitLab 合并请求

TeamCity 对 GitLab merge requests 的处理方式与其对其他托管服务中的拉取请求的处理方式类似。目前，TeamCity 仅检测启用此构建功能后提交的合并请求。

此功能仅监控 refs/merge-requests/*/head 分支上的构建。

以下参数可用于 GitLab 托管类型：

身份验证类型

使用 VCS 根证书 — 如果 VCS 根使用 HTTP(S) 获取 URL，TeamCity 会尝试从 VCS 根设置中提取登录凭据或访问令牌。如果 VCS 根采用匿名身份验证，此选项不起作用。
个人访问令牌 — 使用 GitLab 签发的个人访问令牌。它必须具有 api 作用域。
可刷新访问令牌是由 TeamCity 通过现有的 OAuth 连接从所需的 VCS 提供商获取的短期令牌（与用户在 VCS 托管端手动颁发的静态 PAT 令牌不同）。有关生成和使用可刷新令牌的更多信息，请参阅以下文章：管理可刷新访问令牌。

按源分支

将监控的合并请求限制为与此分支筛选器匹配的源分支。留空则不应用筛选器。

按目标分支

将监控的合并请求限制为与此分支筛选器匹配的目标分支。留空则不应用筛选器。

忽略草稿

默认情况下，拉取请求构建功能会加载 GitLab 草稿合并请求信息并对其运行构建 — 构建页面会在合并请求编号旁显示灰色图标和草稿状态。

勾选此框以忽略 GitLab 草稿合并请求。 TeamCity 不会加载草稿合并请求信息，并且合并请求会被忽略，直到其状态更改为非草稿。

服务器 URL

用于连接的 GitLab URL。如果留空，URL 将从 VCS 根获取 URL 中提取。

Azure DevOps 拉取请求

此功能仅监控 refs/pull/*/merge 分支上的构建。

对于 Azure DevOps ，TeamCity 会在合并分支上检测请求 — 而不像其他 VCS 那样在拉取请求本身上检测。每个构建都在一个虚拟分支上启动，该分支显示合并 PR 后构建的实际结果，因此构建同时包含带有更改的提交和虚拟合并提交。

请注意，该功能会忽略 Azure DevOps 草稿拉取请求。

身份验证类型

个人访问令牌 — 一个静态令牌，您可以在 Azure DevOps 账户设置中签发。签发的令牌应具有 代码（读取） 作用域，以允许拉取请求检索所需信息。
可刷新访问令牌是由 TeamCity 通过现有的 OAuth 连接从所需的 VCS 提供商获取的短期令牌（与用户在 VCS 托管端手动颁发的静态 PAT 令牌不同）。有关生成和使用可刷新令牌的更多信息，请参阅以下文章：管理可刷新访问令牌。

按源分支

将监控的拉取请求限制为与此分支筛选器匹配的源分支。留空则不应用筛选器。

按目标分支

将监控的拉取请求限制为与此分支筛选器匹配的目标分支。留空则不应用筛选器。

项目 URL

用于与远程 Azure DevOps 服务器同步的项目 URL。建议用于本地 Azure DevOps 安装。如果留空，URL 将基于 VCS 根获取 URL 组成。

JetBrains Space 合并请求

此功能会直接监控源仓库的源分支中的合并请求。如果有多个合并请求从同一源分支提交，TeamCity 会在构建结果中显示所有这些请求。但是，只有来自符合筛选器条件的开放请求的提交才会显示为构建的更改。

以下参数适用于 JetBrains Space 托管类型：

连接: 选择一个预配置的连接到 JetBrains Space。
按目标分支: 将监控的合并请求限制为与此分支筛选器匹配的分支。留空则不应用筛选器。

如果您想要运行多个并行构建以预测试合并前的请求，最好的解决方案是：

创建一个复合构建配置，并将您的 JetBrains Space VCS 根与空的分支规范关联起来。
在构建链的末尾添加复合构建配置，通过配置其对并行构建的快照依赖项以及测试。
向每个构建链中的构建配置添加 Pull Requests 功能，以便所有构建都可以检测合并请求分支中的更改。您可以在构建配置模板中预配置所有设置，然后基于此创建这些构建配置。
在组合构建配置设置中：
- 添加一个 VCS 触发器，用于在合并请求分支中检测到更改时自动运行构建。
- 添加 Commit Status Publisher 功能，以将构建状态发送到 JetBrains Space 中的提交详细信息。如果希望链中的其他构建向 JetBrains Space 报告其状态（例如部署或集成测试构建），请将提交状态发布器功能添加到相应的构建配置。

之后，TeamCity 会自动对提交到 JetBrains Space 仓库的合并请求分支中的更改运行构建，并将构建状态发布到 Space 中的合并请求时间线：

为了保护 JetBrains Space 分支不受未经验证的合并请求影响，您也可以在仓库设置中配置 Quality Gates。如果将 TeamCity 构建设置为外部检查，JetBrains Space 会要求合并请求上的构建成功完成后，才允许合并该请求。

查看处理 JetBrains Space 合并请求的已知问题这里。

预定义的拉取请求构建参数

TeamCity 提供了多个预定义构建参数，这些参数会为启用了拉取请求功能的构建公开有价值的拉取请求信息：

teamcity.pullRequest.number //pull request number
teamcity.pullRequest.title //pull request title
teamcity.pullRequest.source.branch //VCS name of the source branch; provided only if the source repository is the same as the target one
teamcity.pullRequest.target.branch //VCS name of the target branch

您可以在构建配置的设置或构建脚本中使用这些参数。

拉取请求工作流程示例

假设您已经设置了以下环境：

公开的 GitHub 仓库 web-app 带有默认分支 master。
TeamCity 项目。
- 构建配置 web-app 使用来自 web-app 仓库的文件，以构建一个网络应用程序。

组织成员通过向 master 分支发送拉取请求来提出对源代码的更改，并且希望这些更改在合并之前自动在 TeamCity 中构建和测试。 TeamCity 可以检测发送到 master 分支的每个拉取请求，并基于更新后的源代码构建 Web 应用程序。

要在 TeamCity 中为 web-app 构建配置配置此工作流程：

在构建配置中添加一个 VCS root:
- 打开配置设置，并导航到 版本控制设置设置选项卡。
- 点击附加 VCS 根。
- 配置根参数：
  - VCS 类型: Git
  - VCS 根名称： \<unique_root_name\>
  - 获取 URL： \<GitHub_repository_URL\>
  - 默认分支: 要监控的分支；默认情况下为 refs/heads/master （阅读更多关于功能分支的信息）
  - 分支规范: 要监控的附加分支的过滤器（例如， +:refs/heads/*）
  - 验证设置是具有 web-app 存储库访问权限的 GitHub 用户
- 测试连接，如果成功，请点击创建。
将 Pull Requests build feature 添加到构建配置：
- 打开配置设置并导航到 构建功能设置选项卡。
- 点击添加构建功能。
- 配置特性参数：
  - VCS Root（VCS 根）: 在步骤 1 中创建的 VCS 根
  - VCS 托管类型: GitHub
  - 身份验证类型: 使用 VCS 根凭据，或选择访问令牌以改用 GitHub 令牌
  - 拉取请求过滤:
    - 由作者: 同一组织的成员
    - 按目标分支: 留空以应用无过滤器并监控存储库中的所有新拉取请求，或明确指定目标分支（在此示例中为 master）
- 测试连接，如果成功，请点击保存。
在构建配置中添加一个 VCS 触发器。

通过此集成，每当您的 GitHub 组织的成员向 master 分支发送 pull request 时，TeamCity 会执行以下操作：

检测发送到 master 分支的拉取请求。
运行 web-app 构建配置：根据您预定义的构建步骤，收集源代码，进行构建和测试应用程序。
在构建配置概述页面上显示已处理拉取请求的信息。您可以立即查看拉取请求状态（1）并刷新其状态信息（2）。

专业提示

您可以进一步自动化您的设置，以便 TeamCity：

构建完成后，使用 Commit Status Publisher 构建功能将构建状态发送回 GitHub。
如果构建成功完成，则在 GitHub 中合并 pull request，使用 Automatic Merge 构建功能。
如果您想在一次拉取请求上运行整个 build chain ，请记住在链中的每个构建配置中添加 Pull Requests 功能。为简化此操作，可以在构建配置模板中设置所有内容，然后基于该模板创建这些构建配置。

故障排查

TeamCity 记录事件与拉取请求构建功能相关的 teamcity-pull-requests.log 文件。应用 "debug-pull-requests" 预设，以在此日志中包含 DEBUG 级别事件。

2026年 9月 11日