Pull Request

拉取请求 构建功能增强了 TeamCity 与 GitHub，Bitbucket Server，Bitbucket Cloud，GitLab，Azure DevOps 和 JetBrains Space 存储库中拉取（合并）请求的集成。

常见信息

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

在构建配置的概览页面上查看拉取请求分支及其待处理的更改。
在构建结果页面的概览选项卡上查看拉取请求的详细信息。
在草稿拉取请求的情况下，图标显示为灰色，而且在拉取请求编号前会出现 Draft 状态：
设定特定的标准，来决定监控哪些 pull 请求。您可以根据作者、目标以及源分支来过滤拉取请求。
请注意，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 根的交互部分）。

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

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

为防止这种情况发生，不要配置 VCS 触发器和 Pull Requests 构建功能，以防止未经验证的拉取（合并）请求更改可以自动开始构建。相反，您可以在查看和验证传入的更改后手动开始新的构建，或者设置不受信任的构建来要求对外部拉取请求进行额外的审查。

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

如果您的项目针对的是 GitHub 或 GitLab 仓库，您可以通过让 TeamCity 构建拉取请求分支并合并那些成功构建的请求，从而进一步自动化您的设置。为了实现这个目标，除了添加 Pull Requests 外，还需添加 Automatic Merge 构建功能。

与 VCS 根的交互

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

如果您只想构建只的拉取请求，请清除 VCS 根的分支规格。

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

下面的示例说明了如何正确设置您的 TeamCity 项目，以便根分支规格和 Pull Requests 功能相互配合，实现以下工作流程：

TeamCity 只跟踪 主要、 生产 和 沙箱 分支，以及所有以 "release-" 开头的分支（例如， release-2077.02）。
开发人员可以创建本地分支，而无需对 TeamCity 进行任何暴露工作。
当开发者准备发布他们的更改时，他们可以创建一个请求，将他们的提交从个人（未跟踪）合并到核心（跟踪）分支。这将会在GitHub上生成一个新的 pull branch（例如， refs/pull/54）。拉取请求"功能将检测到这个新的分支，使其能够在 TeamCity 中构建和测试更改，然后再进行合并。
由于功能的 按作者筛选设置， TimCity 忽略了为未授权（外部）用户请求创建的类似 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` 组合才会生效。
	访问令牌	使用个人访问令牌，或通过 OAuth 连接获取令牌。它必须具有 `public_repo` （用于公共仓库）或 `仓库` （用于私有仓库）的范围。
	GitHub 应用程序访问令牌	通过 GitHub 应用程序发布的非个人短期令牌。这个选项仅在 VCS Root 设置指向特定的 VCS 根目录，并且此根目录是使用 GitHub App connection 配置的情况下可用。
由作者过滤器仅适用于公共仓库。	同一组织的成员	仅检测由 GitHub 中同一组织的成员提交的拉取请求。
	成员和外部合作者	仅检测由同一组织的成员和 GitHub 中的外部协作者提交的拉取请求。
	每个人	检测所有的 pull requests。请注意，选择此选项可能会允许任意用户在您的构建代理上执行恶意代码。
按源分支		定义分支过滤器仅用于监控符合特定条件的源分支上的拉取请求。如果留空，将不适用任何过滤器。
按目标分支		定义 branch filter ，以仅监视符合指定条件的目标分支上的拉取请求。如果留空，将不适用任何过滤器。
忽略草稿		默认情况下，Pull Requests 构建功能会加载 GitHub 草稿拉取请求的信息，并对草稿拉取请求进行构建。构建页面显示了一个变灰的图标，以及与合并请求编号相邻的草稿状态。勾选此框以忽略 GitHub 的草稿拉取请求。 TeamCity 将不会加载草稿拉取请求的信息，直到其状态发生变化。
服务器 URL		指定一个用于连接的 GitHub 网址。如果留空，URL 将从 VCS 根获取 URL 中提取。

Bitbucket Server / Data Center 拉取请求

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

形参	描述
身份验证类型	使用 VCS 根凭证 — 如果 VCS 根使用 HTTP(S) 获取 URL，TeamCity 会尝试从 VCS 根设置中提取用户名 / 密码凭证。如果 VCS 根使用 SSH 提取 URL 或采用匿名身份验证，此选项将无法工作。用户名/密码 — 指定一个用户名和密码以连接到 Bitbucket Server / Data Center。您可以提交访问令牌，而不是密码。令牌应具有对项目和仓库的 Read 权限。可刷新的访问令牌 — 显示配置的 Bitbucket Server / Data Center OAuth 2.0 连接的列表。点击连接旁边的 Acquire 按钮，该连接将用于发出短期有效的 OAuth 令牌。仅项目中配置的 OAuth 连接（或其父级）包含在此列表中。为了使用此认证选项，必须至少配置一个 OAuth 连接。
用户名/密码	指定用于连接到 Bitbucket Server 的用户名和密码。您可以提交访问令牌，而不是密码。令牌应具有对项目和仓库的 Read 权限。
按源分支	定义分支过滤器仅用于监控符合特定条件的源分支上的拉取请求。如果留空，将不适用任何过滤器。
按目标分支	定义 branch filter ，以仅监视符合指定条件的目标分支上的拉取请求。如果留空，将不适用任何过滤器。
服务器 URL	指定一个用于连接的 Bitbucket 网址。如果留空，URL 将从 VCS 根获取 URL 中提取。
使用拉取请求分支	此选项仅用于向后兼容。启用检测官方不支持的 Bitbucket 拉取请求分支（pull-requests/*），而不是源分支。请注意：在切换后的最后一个小时内提交的更改可能会触发新的构建。

Bitbucket Cloud 拉取请求

由于 Bitbucket Cloud 不为拉取请求创建专用分支，因此此构建功能直接监视源代码库中的源分支（不支持 fork）。如果在构建开始时从同一源分支提交了多个拉取请求，TeamCity 将在构建结果中显示所有这些请求。然而，只有符合过滤条件的开放 PR 中的提交会显示为构建的 Changes。

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

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

设置	描述
身份验证类型	使用 VCS 根凭证 — 如果 VCS 根使用 HTTP(S) 获取 URL，TeamCity 会尝试从 VCS 根设置中提取用户名 / 密码凭证。如果 VCS 根使用 SSH 提取 URL 或采用匿名身份验证，此选项将无法工作。用户名/密码 — 指定一个用户名和密码以连接到 Bitbucket Cloud。我们建议您使用带有 Pull Requests \| Read 权限范围的 app 密码。可刷新的访问令牌 — 展示已配置的 Bitbucket Cloud OAuth 连接列表。点击连接旁边的 Acquire 按钮，该连接将用于发出短期有效的 OAuth 令牌。永久访问令牌 — 输入一个 Bitbucket 仓库访问令牌、项目访问令牌或工作区访问令牌，以配置对仓库、工作区或项目的长期访问。令牌必须用Pull Requests \| Read范围进行配置。
按目标分支	定义 branch filter 以便只监视符合指定条件的分支上的拉取请求。如果留空，将不适用任何过滤器。

设置

描述

身份验证类型

使用 VCS 根凭证 — 如果 VCS 根使用 HTTP(S) 获取 URL，TeamCity 会尝试从 VCS 根设置中提取用户名 / 密码凭证。如果 VCS 根使用 SSH 提取 URL 或采用匿名身份验证，此选项将无法工作。
用户名/密码 — 指定一个用户名和密码以连接到 Bitbucket Cloud。我们建议您使用带有 Pull Requests | Read 权限范围的 app 密码。
可刷新的访问令牌 — 展示已配置的 Bitbucket Cloud OAuth 连接列表。点击连接旁边的 Acquire 按钮，该连接将用于发出短期有效的 OAuth 令牌。
永久访问令牌 — 输入一个 Bitbucket 仓库访问令牌、项目访问令牌或工作区访问令牌，以配置对仓库、工作区或项目的长期访问。令牌必须用Pull Requests | Read范围进行配置。

按目标分支

定义 branch filter 以便只监视符合指定条件的分支上的拉取请求。如果留空，将不适用任何过滤器。

GitLab 合并请求

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

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

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

形参	描述
身份验证类型	使用 VCS 根凭据 — 如果 VCS 根使用 HTTP(S) 抓取 URL，TeamCity 将尝试从 VCS 根设置中提取登录凭据或访问令牌。如果 VCS 根使用匿名身份验证，此选项将无法工作。个人访问令牌 — 使用在 GitLab 中发行的个人访问令牌。它必须具有 `api` 范围之一。 GitLab 应用令牌 — 显示已配置的 GitLab OAuth 连接列表。点击连接旁边的 Acquire 按钮，该连接将用于发出短期有效的 OAuth 令牌。
按源分支	定义分支过滤器，仅监控符合指定标准的源分支上的合并请求。如果留空，将不适用任何过滤器。
按目标分支	定义分支过滤器，只监控符合指定条件的目标分支上的合并请求。如果留空，将不适用任何过滤器。
忽略草稿	默认情况下，拉取请求构建功能会加载 GitLab 草案合并请求的信息，并在草案合并请求上运行构建。构建页面显示了一个变灰的图标，以及与合并请求编号相邻的草稿状态。勾选此框以忽略 GitLab 草稿合并请求。 TeamCity将不会加载草稿合并请求信息，合并请求在其状态变为非草稿前将被忽略。
服务器 URL	指定一个用于连接的 GitLab URL。如果留空，URL 将从 VCS 根获取 URL 中提取。

Azure DevOps 拉取请求

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

在与 Azure DevOps 的情况中，TeamCity 检测到的是对合并分支的请求 - 而不是像其他 VCSs 那样在拉取请求本身上。每次构建都将在一个虚拟分支上启动，展示合并 PR 后的实际构建结果。因此，构建将包含更改的提交和虚拟合并提交。

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

身份验证设置

个人访问令牌 — 您可以在您的 Azure DevOps 帐户设置中发行的静态令牌。您发出的令牌应具有 代码（读取） 权限范围，以允许 Pull Requests 检索所需的信息。
可刷新的访问令牌 - 通过配置的 Azure OAuth 2.0 连接发行的短期令牌。点击旁边的 Acquire 按钮获取所需连接的访问令牌。

Pull Request 筛选

按源分支 — 这是一个分支过滤器，仅用于监控符合指定条件的源分支上的拉取请求。如果留空，将不适用任何过滤器。
按目标分支 — 这是一个分支过滤器，只用于监控符合指定条件的目标分支上的拉取请求。如果留空，将不适用任何过滤器。

其他设置

项目 URL—— 一个用于与远程 Azure DevOps 服务器同步的项目 URL。我们建议在本地部署的 Azure DevOps 安装中使用此字段。如果留空，URL将根据VCS根获取URL进行构建。

JetBrains Space 合并请求

这个功能直接在原始仓库的源分支中监视合并请求。
如果从同一源分支提交了多个合并请求，TeamCity 将在构建结果中显示所有这些请求。然而，只有与过滤标准相匹配的开放请求中的提交才会显示为构建的 Changes。

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

形参	描述
连接	选择一个预配置的连接到 JetBrains Space。
按目标分支	定义分支过滤器，仅监视符合指定条件的分支上的合并请求。如果留空，将不适用任何过滤器。

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

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

在此之后，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 仓库的文件，以构建一个网络应用程序。

您的组织的成员通过发送 pull 请求给 master 分支来提出源代码的修改建议，您希望在将这些更改合并之前，TeamCity 可以自动地构建和测试它们。
TeamCity 能够检测到发送给 master 分支的每一个 pull 请求，并根据更新的源代码构建 web 应用程序。

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

将 VCS root 添加到构建配置中：
- 前往 Build Configuration Settings | Version Control Settings 然后点击 Attach VCS root。
- 配置根参数：
  - 版本控制系统的类型：Git
  - VCS 根目录名称：<unique_root_name>
  - 获取 URL：<GitHub_repository_URL>
  - 默认分支：需要进行监控的分支；默认情况下，refs/heads/master （更多关于功能分支的内容）
  - 分支规格：用于监视额外分支的过滤器（例如，+:refs/heads/*）
  - GitHub 用户的认证参数具有访问 web-app 存储库的权限
- 测试连接，如果成功，点击 Create。
将 Pull Requests 构建功能添加到构建配置中：
- 转到 Build Configuration Settings | Build Features ，然后点击 Add build feature。
- 配置特性参数：
  - VCS Root：在步骤1中创建的 VCS 根目录
  - 版本控制系统托管类型： GitHub
  - 认证类型：使用 VCS 根证书，或选择 访问令牌 以使用 GitHub 令牌代替
  - Pull Requests 筛选：
    - 由作者：同一组织的成员
    - 按目标分支：置空以不应用任何过滤器并监视存储库中的所有新拉取请求，或者明确指定目标分支（在此例中，master）
- 测试连接，如果成功，请点击保存。
在构建配置中添加一个 VCS 触发器。

就是这样！现在，每当您的 GitHub 组织的成员向 master 分支发送拉取请求时，TeamCity 将如下操作：

检测发送到 master 分支的拉取请求。
运行 web-app 构建配置：根据您预定义的构建步骤，收集源代码，进行构建和测试应用程序。
在构建配置概览页面上显示有关处理的 pull request 的信息。您可以立即查看拉取请求状态（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 级别的事件。

最后修改日期： 16日 7月 2024年