Branch Filter
If a VCS root has branches specified, the branch filter option becomes available for various operations in TeamCity.
Branch Filter Usage
Currently, branch filters can be configured on the following TeamCity settings pages:
Settings | Branch filter description |
|---|---|
Version Control Settings of a build configuration | Limit the set of branches available for the build configuration. This branch filter is applied before any other branch filter and limits branches shown in the custom build dialog, as well as branches visible to triggers and build features. |
Limit dependency builds, whose artifacts will be used in the builds of the current configuration, to those in the matching branches. | |
Limit the set of branches where builds will be monitored by this finish build trigger. | |
Limit the set of branches in which builds can be triggered by this VCS trigger. | |
Limit the set of branches the trigger should be applied to.
| |
Set a branch filter to rerun failed builds only in branches that match the specified criteria. | |
VCS labeling build feature | Limit the set of branches to whose builds the labels will be applied. |
Automatic merge build feature | Limit the set of branches which builds’ sources will be merged. |
Notification rules and the Notifications build feature | Set a filter to receive alerts only on the builds from the specified branches. By default, only the default branch is monitored. |
Pull Requests build feature | Specify on which branches to monitor and trigger pull requests. Filters for this feature should reference branches by their fully qualified VCS names ( |
Specify a naming pattern for branches to which the clean-up rule will apply. Note that, depending on the " Apply rule " settings, it could either apply to a selected number of builds per each matching branch or to a selected number of builds once per set of matching branches. |
If there are multiple branch filters configured atop a single root, the following order of priority is applied:
The branch specification in the VCS root settings defines the initial set of the monitored branches.
If specified, a branch filter in the Version Control Settings of a build configuration can narrow down the initial set of branches.
If specified, a branch filter in the settings of a build trigger applies to the subset declared by the filter (2).
Branch Filter Format
To filter branches, use a newline-delimited list of +|-:logical_branch_name rules, where logical_branch_name is the name displayed in the TeamCity UI (for example, master). The name is case-sensitive.
The +: rules include the matching branches into the list of accepted branches, the -: rules exclude the branches from the list.
Each rule can have one optional wildcard * placeholder that matches one or more characters: +|-:name* will match the branch name1 but will not match the branch name, which will need to be added explicitly.
You can use parameter references in the branch filter.
When a single branch is matched by several lines of the branch filter, the most specific (least characters matched by a pattern) last rule applies. That is, if the filter contains an exact pattern matching the branch (i.e. a pattern without the * wildcard), then the last such pattern is used.
Other examples:
Only the default branch is accepted:
+:<default>All branches except the default one are accepted:
+:* -:<default>Only branches with the
feature-prefix are accepted:+:feature-*Empty branch filter (all branches are accepted):
+:*