TeamCity配置BranchFilter隐藏默认分支后提示分支禁用报错如何解决

问题根因 #

你误用了全局分支过滤器实现分支隐藏需求：-:<default>规则的作用是完全禁止默认分支的所有构建操作，TeamCity收集变更时会优先校验默认分支的构建权限，因此哪怕你手动选择release分支触发，也会触发报错。该过滤器的设计用途是控制允许构建的分支范围，而非控制UI侧的分支列表展示。 #

官方合规解决方案 #

方案1：仅隐藏master分支、保留构建权限（适用于偶尔需要在该任务构建master的场景）

1. 恢复构建配置的全局分支过滤器为默认规则，删除原有-:<default>配置：

+:*

2. 进入构建配置的「版本控制设置」页面，找到源代码对应的VCS Root，点击编辑分支规则。
3. 在分支规则配置区找到「分支显示过滤器」（TeamCity 2020.2及以上版本原生支持，位于分支规范输入框下方），添加如下规则：

+:*
-:master

该规则仅作用于UI侧的分支下拉列表展示，不会影响变更收集、构建权限校验逻辑，配置后master分支不会出现在可选列表中，手动触发release分支不会再报错。
4. 可选优化：进入「常规设置」页，将手动触发的默认分支设置为任意活跃的release分支，避免手动触发时默认选中未展示的master分支。 #

方案2：完全禁止该任务构建master分支（适用于该任务仅处理release分支的场景）

由于你已经有单独的master构建任务，release任务完全不需要处理master分支，可直接调整源代码VCS Root的分支规范，移除master的匹配规则即可：

Default branch: refs/heads/master
Branch specification:
+:refs/heads/(release/*)

配置后master分支既不会出现在分支列表中，也无法在该任务中被构建，同时因为没有禁用默认分支的构建权限，变更收集逻辑不会触发报错。工具脚本对应的VCS Root无需修改，仍可正常拉取master分支的脚本资源。 #

补充说明 #

你之前尝试通过teamcity.build.branch参数覆盖分支配置无效，是因为该参数仅指定构建使用的目标分支，不会绕过全局分支过滤器对默认分支的校验逻辑，因此无法解决根因问题。

内容的提问来源于stack exchange，提问作者Kumazatheef