TeamCity 2019.1 Help

Branch Filter

If a VCS Root has branches configured, you can use the Branch Filter option.

On this page:

Branch Filter Usage

The Branch Filter allows limiting branches used by TeamCity in various operations. Currently, the Branch Filter is available 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.

Finish Build Triggers

Limit the set of branches to which builds the trigger should be applied to.

VCS Triggers

Limit the set of branches the trigger should be applied to.

Schedule Triggers

Limit the set of branches the trigger should be applied to.

  • If "Trigger build only if there are pending changes" is turned ON, then the trigger will add a build to the queue for all branches matched by the trigger branch filter where pending changes exist

  • If "Trigger build only if there are pending changes" is turned OFF, then the trigger will add a build to the queue for all branches matched by the trigger branch filter regardless of the presence of pending changes there.

‘VCS labeling’ build feature

Limit the set of branches to which builds the labels will be applied.

‘Automatic merge’ build feature

Limit the set of branches branches which builds’ sources will be merged.

Notification rules

Set a filter to receive alerts only on the builds from the specified branches. By default, only the default branch is monitored.

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 +: 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):

    +:*