Branch Filter | TeamCity Cloud Documentation

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.
Artifact dependency	Limit dependency builds, whose artifacts will be used in the builds of the current configuration, to those in the matching branches.
Finish build triggers	Limit the set of branches where builds will be monitored by this finish build trigger.
VCS triggers	Limit the set of branches in which builds can be triggered by this VCS trigger.
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 matching branches 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 matching branches regardless of the presence of pending changes there.
Retry build triggers	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 (`refs/heads/branch-`) instead of shortened logical names (`branch-`).
Keep rules for clean-up	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):
+:*

Pull Request Branch Filters

Use the +|-pr: <parameter1>=<value1> <parameter2>=<value2> ... syntax to create filters that target specific pull (merge) request branches. This universal syntax allows you to define fine-grained VCS-agnostic filter expressions that consider more specific parameters than just logical branch names.

The <parameter>=<value> expressions are combined using the logical AND operator, meaning a pull (merge) request branch must satisfy all conditions to pass the filter. Currently, the following parameters and values are supported:

target and source — allow you to filter requests by their incoming and outgoing branches. The source parameter is always false if a request originates from a forked repository. Supported values: logical branch names with optional wildcards.
sourceRepo — allows you to target only pull requests from the same repository (for example, when merging one repository branch into another), from forked repositories, or both. Supported values: same, fork, any.
draft — specifies whether draft pull requests are accepted. This parameter is in effect only for GitHub and GitLab. Supported values: true to accept only requests labeled as drafts; false to accept only non-draft requests.

github_role — allows you to filter pull (merge) requests by sender roles (relative to the repository organization). Supported values: collaborator, contributor, member, owner, none (not case-sensitive).

When setting up branch filters, click the magic wand button and switch to the Pull Request condition tab to add filter expressions using a visual editor.

Wildcards and Patterns

Use the asterisk ("*") as a wildcard for any string. For example, the +pr:* and -pr:* rules allow triggers to accept or ignore all incoming requests.

The following rule allows an object to accept only those requests whose target branch starts with "dev/":

+pr:target=dev/*

Filter Priority

Pull request filter expressions are applied in the same manner as regular +|-:<branch_name> expressions: one by one starting with the first one. This means in case of conflicting expressions, the last one has the highest priority. For example, the following ruleset allows its parent object to accept all available branches, then excludes all pull request branches, and finally re-enables pull requests authored by organization members.

+:*
-pr:*
+pr:github_role=member

The following combination of filters rejects pull requests coming from forked repositories even if they target the main branch (since the sourceRepo condition comes last).

+pr:target=main
-pr:sourceRepo=fork

Example

The following Kotlin DSL sample illustrates how to combine VCS and Schedule triggers to implement the following setup:

Changes in existing branches are build as soon as TeamCity detects them;
Non-draft pull (merge) requests authored by organization members are built as soon as TeamCity collects information about them;
Non-draft pull (merge) requests from collaborators and contributors are built nightly at 3:00 AM if these requests target one of the two stable repository branches.

object Build : BuildType({
  triggers {
    vcs {
        branchFilter = """
            +:*
            -pr:*
            +pr: draft=false github_role=MEMBER
        """.trimIndent()
    }
    schedule {
        schedulingPolicy = daily { hour = 3 }
        branchFilter = """
            +pr: draft=false github_role=COLLABORATOR target=main
            +pr: draft=false github_role=COLLABORATOR target=development
            +pr: draft=false github_role=CONTRIBUTOR target=main
            +pr: draft=false github_role=CONTRIBUTOR target=development
        """.trimIndent()
        triggerBuild = always()
    }
  }
  features {
    pullRequests {
      vcsRootExtId = "${MyRoot.id}"
      provider = github {
        authType = vcsRoot()
        filterAuthorRole = PullRequests.GitHubRoleFilter.EVERYBODY
      }
    }
  }
})