TeamCity On-Premises 2024.03 Help

使用功能分支

Feature branches 在分布式版本控制系统(DVCS)中允许您独立于主开发流程工作,并将所有的功能变更提交到该分支中,在功能完成后将变更融入主分支。 这种方法为软件开发团队带来了许多优势;然而,在没有专门支持的持续集成服务器中,也引发了一些问题,如持续的构建配置复制、可见性差,最终导致无法控制整个过程。

TeamCity 对功能分支的支持持续扩展,并包括在每次 TeamCity 检测到构建配置的 VCS 根的特定分支中有变化时,Branch Remote Run Trigger 开始新的个人构建,以及在成功构建后将一个分支合并到另一个分支的 Automatic Merge 等其他功能。

支持的版本控制系统

GitMercurial 功能分支得到了支持,同样还支持 Perforce branch streams support

配置分支

要开始使用 DVCS 分支,您需要配置需要监视哪些分支的更改。 这是在 GitMercurial VCS根的 常规设置 部分通过 分支规格 字段完成的。在Perforce中,勾选对应的框以启用功能分支支持,这将显示分支规格字段。 该字段接受一个分支名称或模式的列表。 TeamCity 会监控与分支规格匹配的分支,此外还有 default branch

一旦您配置了分支规范,TeamCity 将开始监视这些分支的变化。 如果您的构建配置有 一个 VCS 触发器并且在某个分支中找到了变更,TeamCity 将在此分支中触发构建。 从构建配置主页,您也可以按分支名称过滤历史记录、更改日志、挂起的更改和问题日志。 分支名称也会出现在自定义构建对话框中,因此您也可以在分支上手动触发自定义构建。

分支规格字段的语法是由 +|-:branch_name 规则构成的分行列表。

每条规则可以有一个可选的 * 占位符,匹配一个或者多个字符。
例如, +":refs/heads/teamcity* 匹配所有以 refs/heads/teamcity 和至少一个附加字符开始的分支。
带有 refs/heads/teamcity 的分支将不会被匹配。

branch_name 参数是针对 VCS 的,即在 Git 中的 refs/heads/master

分支规范

星号( * )通配符匹配的分支名称部分将变为在 TeamCity 用户级界面中显示的短分支名称(也称为逻辑分支名称)。 该行也可以包含可选的括号,当出现时,表示该部分的模式将被用作逻辑名称,而不仅仅是*-匹配的符号。

您可以在分支规格中使用参数。

当一个单一的 VCS 分支被分支规格的多行匹配时,最具体的(模式匹配的字符最少的)最后一条规则适用。

也就是说,如果规格中包含一个与分支完全匹配的模式(即,没有使用 * 通配符的模式),那么会使用最后一个这样的模式。 所以,如果您有像这样的规格:

+:refs/heads/release-v1 -:refs/heads/release-v1

那么最后一个模式将会胜出,此分支将会被排除。

如果一个分支规范有几个带有 * 通配符的模式,那么 TeamCity 会选择产生最短逻辑名称的模式。 这个分支规格:

+:refs/heads/*/hotfix -:refs/heads/v1/*

将包括 refs/heads/v1/hotfix 分支(因为 v1hotfix 短)
如果有2个带有 * 通配符的模式产生了相同长度的逻辑名称,那么最后的模式将胜出。

注释和服务表达式

分支规格也支持以 # 字符开头的表达式。 与定义应包含或排除到(来自)规格的分支名称的常规表达式相反,这些是为特定任务设计的特别制作的“服务”行。

  • # 开头的任何行都被视为常规注释。

    +:refs/heads/main # Exclude legacy branch. DO NOT REMOVE! -:refs/heads/release-v1
  • #! 转义:<您的字符> 表达式定义了一个转义字符,允许您在分支名称中使用特殊字符。 例如,要为 "release-(7.1)" 分支编写分支规格规则,您需要转义圆括号。 如果您想使用反斜线( \ )作为转义字符,您的最终分支规范可以如下所示:

    #! escape: \ +:release-\(7.1\)
  • #! fallbackToDefault: false 表达式允许您在找不到必需的分支时,禁止 TeamCity 使用一个 默认分支。 例如,当您使用 TeamCity REST API 启动一个不存在的分支的构建时(默认情况下,TeamCity 会在这种情况下为默认分支运行新的构建)。

    #! fallbackToDefault: false +:included_branch -:excluded_branch

特定分支的构建配置设置

借助 版本设置,您可以为每个存储库分支创建具有可变设置的构建配置。 请参阅以下文章以获取示例:特定分支设置

默认分支

在为 DVCS 配置 VCS 根时,您需要指定要用作默认的分支名称。 默认分支具有特殊含义:

  • 当分支未指定或所指定的分支未被分支规范所包含时(例如,当有人只是点击 Run 而未选择一个分支),它是一个回调分支。

  • 在显示构建和更改的序列并且到达分支创建的那一刻时,可以使用它。

  • 默认分支允许在不同的 VCS 根目录(例如,一个根目录是 Git ,另一个是 Mercurial )以及在它们通过快照依赖关系链接时的不同构建中使用不同的分支。 当在默认分支中触发顶链构建时,其所有依赖项也将在各自的默认分支中构建。

除非通过 分支过滤器 禁用,否则默认分支总是隐式包含在分支规格中。 在 TeamCity UI 中, 默认分支以更深颜色标记的分支标记进行标记。

我的分支

TeamCity 能够根据当前 TeamCity 用户的提交来识别并分组分支。

在分支筛选器中选择 My Branches 群组,以显示所有最后100次更改包含您的提交的活动分支,这是基于定义的 VSC 用户名。

逻辑分支名称

逻辑分支名称是在构建和构建配置级别的用户界面中显示的分支名称。 逻辑分支名称通常是完整的 VCS 特定分支名称的一部分。 它是通过将分支规格应用于版本控制中的分支名称来计算的。

例如,如果分支规格定义如下:

+:refs/heads/*

那么,由 * 匹配的部分(例如, master )是一个逻辑分支名称。

如果分支规格模式使用了括号,逻辑名由括号内的名字部分组成;要在 VCS 分支 refs/heads/v8.1/feature1 的 UI 中查看 v8.1 / feature1 逻辑名,请使用这个:

+:refs/heads/(v8.1/*)

您无需将默认分支包含在分支规格中,因为它已经被隐式地包含在其中了。 然而,如果您希望在用户界面中为默认分支设置一个简短的逻辑分支名称,例如, master ,您可以将其包含在分支规格中并使用括号:

+:refs/heads/(master)

构建

您可以通过以下两种方式之一在特定分支上手动运行构建:

  • 在构建列表中,点击所需分支对面的 Run

  • 打开 自定义运行 对话框,转到 更改 标签页,并在 "构建分支" 下拉菜单中选择所需的分支。

要自动从特定分支或一组分支运行构建,配置 构建触发器

分支构建在 TeamCity 用户界面中很容易被识别出来,因为它们会被标记上一个特殊的标签:

从分支构建

如果您对某个特定的分支感兴趣,您也可以按分支名称过滤历史记录。 TeamCity 也会为来自默认分支的构建分配一个分支标签。

更改

对于每个构建,TeamCity 都会显示其中包含的更改。 对于来自分支的构建,更改的计算过程会考虑分支,并向您展示与构建分支相关的更改。 在分支中的构建所做的更改将计算为从构建的修订版到分支中的上一个构建或默认分支中的构建的更改。
提交记录的更改日志及其图形会帮助您理解正在监视的分支中正在发生的情况。

构建更改

在默认情况下启用了 Show graph 选项后,TeamCity 会在图表上显示构建标记。

活动分支

在配置了分支的构建配置中,大多数 UI 页面默认显示活动分支。

一个 活跃分支 是具有最近活动的分支:它有最近的构建或者在带有最近提交的仓库中存在。

活动的阈值可以通过构建配置参数进行配置。 参数可以在构建配置(这将仅影响一个构建配置)、项目中更改,或者在 内部属性 中更改(这将为整个服务器定义默认值)。 在配置中的参数会覆盖 内部属性 中的参数。

如果满足以下条件,分支将被视为活动状态:

  • 它存在于 VCS 仓库中,并且有近期的提交(即,提交的时间小于整数参数 teamcity.activeVcsBranch.age.days 的值,默认为 7 天)。

  • 或者它有最近的构建(即,构建的时间小于整数参数 teamcity.activeBuildBranch.age.hours 的值,默认为24小时)。
    具有构建的已关闭 VCS 分支在最后一次构建后的 24小时内仍将显示为活动状态。 要从显示中移除已关闭的分支,请设置 teamcity.activeBuildBranch.age.hours=0

测试

TeamCity 试图在构建中检测新的失败测试,对于那些并非新的测试,您可以看到测试在哪个构建中开始失败。 此功能也能识别分支,即当计算第一个构建时,TeamCity 会遍历同一分支的构建。

此外,在测试详情页上提供了一个 branch filter,您可以在单个分支中查看测试通过或失败的历史记录。

故障条件

如果一个 构建失败条件 被如下配置:构建度量与上一次成功/完成/固定构建相比有所改变,TeamCity 将尝试将当前构建与同一分支的构建进行比较。 如果同一分支中没有合适的构建,它将使用默认分支中的构建,并将相应的消息添加到构建日志中。 请注意,如果默认分支被 分支过滤器 禁用,那么 TeamCity 将无法正确处理构建失败的条件(参见相关问题 TW-74884)。

触发器

VCS 触发器完全了解分支,并且一旦在分支中检测到检入,就会触发构建。 所有的 VCS 触发器选项,如每次检入触发、静默周期和触发规则,都直接用于从分支构建。 默认情况下,“Schedule and Finish”构建触发器仅监视默认分支中的构建。

另外,可以为 VCS 、计划和完成构建触发器指定一个 分支过滤器

依赖

如果带有分支的构建配置对其他带有分支的构建配置有快照依赖,那么当在一个分支中触发构建时,链中的其他构建也将获得关联的分支,前提是这些构建中 VCS 根的分支有相同的 逻辑名称,并且该分支没有被分支规范排除。 构建的 VCS 根可以指向不同的存储库,但逻辑分支名称必须相同。

如果满足此条件,将检出具有此名称的分支,并将链下所有构建(构建触发取决于)和链上所有构建(取决于触发的构建)标记为同一分支。 否则,将检出默认分支。

您可以配置构件依赖性,以从特定分支的构建中检索构件:构件依赖性将使用来自指定分支的构建。 同样适用于 ScheduleFinish Build 触发器。

通知

除了 "My changes",所有的通知规则只会在来自默认分支的构建中通知您。 与此同时,"我的更改"规则将适用于所有可用分支的构建。

构建配置状态

构建配置状态是根据默认分支的构建计算的。 因此,针对默认分支的构建,每个配置的调查都能够顺利进行。 例如,来自非默认分支的成功构建不会移除每个配置的调查,但来自默认分支的成功构建将会移除。

多个 VCS 根

如果一个构建配置有两个(或更多)设定了分支过滤器的 VCS 根,触发行为可能会变得更复杂。

VCS 触发器按照它们的 逻辑分支名称 对多个根的分支进行分组。 当某个根节点从另一个根节点没有分支时,将使用其默认分支。

例如:2个 VCS 根具有相同的默认分支 refs/heads/master。 Root1 具有分支规范 refs/heads/7.1/* ,并在分支 refs/heads/7.1/feature1refs/heads/7.1/feature2 中有新的提交。 Root2 具有规格 refs/heads/devel/* ,并且在分支 refs/heads/devel/feature1 中有新的提交。
在这里, feature1 是相关于两个路径不同的分支的逻辑名称: .../7.1/feature1.../devel/feature1

在这种情况下,VCS 触发器将运行 3 次构建,这些构建来自以下分支组合的修订:

Build number(构建号)

root1

root2

描述

1

refs/heads/master

refs/heads/master

默认分支会被隐式添加到每个规格中。

2

refs/heads/7.1/feature1

refs/heads/devel/feature1

feature1 逻辑名称出现在两个根的规格中。

3

refs/heads/7.1/feature2

refs/heads/master

在 root1 的规范中存在 feature2 逻辑名称,但在 root2 的规范中则不存在。 因此,root2 回退到默认分支。

构建参数

如果您需要在构建脚本中获取分支名称,或者将其作为参数在其他构建配置设置中使用,请参考 预定义的构建参数

清理

清理规则独立应用于每个活动分支。

手动分支合并

在 TeamCity 中,您可以手动合并分支,例如,如果您希望在代码审查/批准后才合并分支,或者尽管分支中的测试失败,您仍希望执行合并。

要手动合并源

打开 构建结果页面,点击右上角的 操作 菜单,然后选择 合并此构建源
出现的对话框允许您选择目标分支并添加提交消息(必填)。

也可以自动合并分支。

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