Automatic Merge

Edit pageLast modified: 05 March 2025

The Automatic Merge build feature tracks builds in branches matched by the configured filter and merges them into a specified destination branch if the build satisfies the condition configured (for example, the build is successful).

note

TeamCity also allows merging branches manually.

VCS Support

The feature is supported for build configurations that utilize Git, Mercurial, and Perforce VCS roots. A VCS root must have a branch specification that allows TeamCity to work with at least two branches.

Automatic Merge Settings

Check Adding Build Features for notes on how to add a build feature.
All branches that are used in this feature must be present in a repository and included into the Branch Specification of the current build configuration.

Option

Description

Watch builds in branches

Specify the branches whose builds' sources will be merged. Read more in Branch Filter.

Merge into branch

A logical name of the destination branch the sources will be merged to. Parameter references are supported here. The branch must be present in a repository and included into the Branch Specification.

Merge commit message

A message for a merge commit. The default is set to Merge branch '%teamcity.build.branch%'. Parameter references are supported here.

Perform merge if

A condition defining when the merge will be performed (either for successful builds only, or if build from the branch does not add new problems to destination branch).

Merge policy

Select to create a merge commit or do a fast-forward merge.

For configurations targeting Perforce depots, the Automatic Merge feature always uses merge (p4 merge), never copy (p4 copy). Stream mergeany/mergedown options are ignored.

Run policy

Choose when to merge:

  • Merge after build finish: the build finishes, and then the merge starts. The build duration does not include the merging time. Dependent builds can start even if merging is still in process.

  • Merge before build finish: the build is considered finished only when the merge is completed. Dependent builds will start only after the merge is completed.

Cascading Merge

It is possible to define a cascade of merge operations by adding several such build features to a build configuration.

For example, you want to automatically merge all feature branches into an integration branch, and then configure another merge from the integration to the default branch. To achieve this, you can add two Automatic Merge build features: one watching +:feature-* branches and merging into integration branch and the second watching +:integration branch and merging into default branch. The build configuration should then allow for building feature-* and integration branches.

See also a related TeamCity blog post.