Pull Request
拉取请求 构建功能增强了 TeamCity 与 GitHub,Bitbucket Server,Bitbucket Cloud,GitLab,Azure DevOps 和 JetBrains Space 存储库中拉取(合并)请求的集成。
将 Pull Requests 功能添加到构建配置允许您:
在构建配置的概览页面上查看拉取请求分支及其待处理的更改。
在 构建结果页面的概览选项卡上查看拉取请求的详细信息。
在草稿拉取请求的情况下,图标显示为灰色,而且在拉取请求编号前会出现 Draft 状态:
设定特定的标准,来决定监控哪些 pull 请求。 您可以根据作者、目标以及源分支来过滤拉取请求。
note
请注意,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 能够构建来自拉取(合并)请求分支的变更。
warning
如果您的构建配置针对的是公共仓库,其中不受信任的用户可以推送提交或创建拉取(合并)请求,那么构建这些更改意味着 TeamCity 可以执行其中引入的恶意代码。 例如,TeamCity 可能处理来自源代码的有害的 服务消息,或者应用来自修改了的
.teamcity
文件夹文件的改变后的 项目设置。为防止这种情况发生,不要配置 VCS 触发器 和 Pull Requests 构建功能,以防止未经验证的拉取(合并)请求更改可以自动开始构建。 相反,您可以在查看和验证传入的更改后手动开始新的构建,或者设置 不受信任的构建 来要求对外部拉取请求进行额外的审查。
请查看此部分以获取有关可以修改仓库代码的用户可能导致的潜在损害的更多信息:安全说明。
如果您的项目针对的是 GitHub 或 GitLab 仓库,您可以通过让 TeamCity 构建拉取请求分支并合并那些成功构建的请求,从而进一步自动化您的设置。 为了实现这个目标,除了添加 Pull Requests 外,还需添加 Automatic Merge 构建功能。
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()
})
这个功能支持 GitHub 和 GitHub Enterprise。 它仅监控在 refs/pull/*/head
分支上的构建。
以下参数适用于 GitHub 托管类型:
形参 | 选项 | 描述 |
---|---|---|
身份验证类型 | 使用 VCS 根证书 | 如果 VCS 根使用 HTTP(S) 取回 URL,TeamCity 将尝试从 VCS 根设置中提取用户名/密码凭证或个人访问令牌/ 如果 VCS 根使用匿名认证或 SSH,这个选项将无法工作。 对于 GitHub Enterprise 仓库,只有个人访问令牌 / |
访问令牌 | 使用个人访问令牌,或通过 OAuth 连接获取令牌。 它必须具有 | |
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 的用户名和密码。 您可以提交访问令牌,而不是密码。 令牌应具有对项目和仓库的 Read 权限。 |
按源分支 | 定义分支过滤器仅用于监控符合特定条件的源分支上的拉取请求。 如果留空,将不适用任何过滤器。 |
按目标分支 | 定义 branch filter ,以仅监视符合指定条件的目标分支上的拉取请求。 如果留空,将不适用任何过滤器。 |
服务器 URL | 指定一个用于连接的 Bitbucket 网址。 如果留空,URL 将从 VCS 根获取 URL 中提取。 |
使用拉取请求分支 | 此选项仅用于向后兼容。 启用检测 官方不支持的 Bitbucket 拉取请求分支(pull-requests/*),而不是源分支。 请注意:在切换后的最后一个小时内提交的更改可能会触发新的构建。 |
由于 Bitbucket Cloud 不为拉取请求创建专用分支,因此此构建功能直接监视源代码库中的源分支(不支持 fork)。如果在构建开始时从同一源分支提交了多个拉取请求,TeamCity 将在构建结果中显示所有这些请求。 然而,只有符合过滤条件的开放 PR 中的提交会显示为构建的 Changes。
请注意,VCS 根的分支规范 不能 包含与拉取请求分支匹配的模式。
以下参数可用于 Bitbucket Cloud 托管类型:
设置 | 描述 |
---|---|
身份验证类型 |
|
按目标分支 | 定义 branch filter 以便只监视符合指定条件的分支上的拉取请求。 如果留空,将不适用任何过滤器。 |
TeamCity 对 GitLab merge requests 的处理方式与其对其他托管服务中的拉取请求的处理方式类似。 目前,只有在启用此构建功能后,TeamCity 才能检测到提交的合并请求。
此功能仅监控 refs/merge-requests/*/head
分支上的构建。
以下参数可用于 GitLab 托管类型:
形参 | 描述 |
---|---|
身份验证类型 |
|
按源分支 | 定义分支过滤器,仅监控符合指定标准的源分支上的合并请求。 如果留空,将不适用任何过滤器。 |
按目标分支 | 定义 分支过滤器,只监控符合指定条件的目标分支上的合并请求。 如果留空,将不适用任何过滤器。 |
忽略草稿 | 默认情况下,拉取请求构建功能会加载 GitLab 草案合并请求 的信息,并在草案合并请求上运行构建。 构建页面显示了一个变灰的图标,以及与合并请求编号相邻的 草稿 状态。 勾选此框以忽略 GitLab 草稿合并请求。 TeamCity将不会加载草稿合并请求信息,合并请求在其状态变为非草稿前将被忽略。 |
服务器 URL | 指定一个用于连接的 GitLab URL。 如果留空,URL 将从 VCS 根获取 URL 中提取。 |
此功能仅监控 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进行构建。
tip
如果您正在寻找如何将您的 JetBrains Space 实例与 TeamCity 集成的方法,请查看这个 完全集成指南!
这个功能直接在原始仓库的源分支中监视合并请求。
如果从同一源分支提交了多个合并请求,TeamCity 将在构建结果中显示所有这些请求。 然而,只有与过滤标准相匹配的开放请求中的提交才会显示为构建的 Changes。
以下参数适用于 JetBrains Space 托管类型:
形参 | 描述 |
---|---|
连接 | 选择一个预配置的 连接到 JetBrains Space。 |
按目标分支 | 定义分支过滤器,仅监视符合指定条件的分支上的合并请求。 如果留空,将不适用任何过滤器。 |
如果您想要运行多个并行构建以预测试合并前的请求,最好的解决方案是:
在构建链的末尾添加复合构建配置,通过配置其对并行构建的 快照依赖项 以及测试。
向每个构建链中的构建配置添加 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 级别的事件。
感谢您的反馈!