You are viewing the documentation of TeamCity 10.x and 2017.x, which is not the most recently released version of TeamCity.
View this page in TeamCity 2018.x documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

Skip to end of metadata
Go to start of metadata

Branch Remote Run trigger automatically starts a new Personal Build each time TeamCity detects changes in particular branches of the VCS roots of the build configuration.
At the moment this trigger supports only Git and Mercurial VCSes.

For non-personal builds off branches, please see Working with Feature Branches. When branch specification is configured for a VCS root, Branch Remote Run Trigger only processes branches not matched by the specification.

A trigger monitors branches with names that match specific patterns. Default patterns are:

for Git repositories — refs/heads/remote-run/*
for Mercurial repositories — remote-run/*

These branches are regular version control branches and TeamCity does not manage them (i.e. if you no longer need the branch you would need to delete the branch using regular version control means).

By default TeamCity triggers a personal build for the user detected in the last commit of the branch. You might also specify TeamCity user in the name of the branch. To do that use a placeholder TEAMCITY_USERNAME in the pattern and your TeamCity username in the name of the branch, for example pattern remote-run/TEAMCITY_USERNAME/* will match a branch remote-run/joe/my_feature and start a personal build for the TeamCity user joe (if such user exists).



At the moment there is no UI to show what's going on inside the trigger, so the only way to troubleshoot it is to look inside teamcity-remote-run.log. To see a more detailed log please enable debug-vcs logging preset at Administration | Diagnostics page.

In order to trigger a build branch should have at least one new commit comparing to the main branch.

Example: Run a personal build from a command line.


With the default pattern (refs/heads/remote-run/*) command git branch -r will list your personal branches. If you want to hide them, change the pattern to refs/remote-run/* and push your changes to branches like refs/remote-run/my_feature. In this case your branches are not listed by the above command, although you can see them anyway using git ls-remote <url of git repository>.



If your build configuration has more than one VCS root which support branch remote-run, and you push changes to all of them, TeamCity will start several personal builds with changes from one VCS root each.

See also:

Administrator's Guide: Git | Mercurial

  • No labels


  1. Does pattern supports regexps?

    I have about 500 branches. I want allow this feature for branches like:

    • SOMEPRJ-123_some_description
    • OTHERPRJ-312_another_description

    How should looks my pattern? I want use regexp like: "/(\w+)-(\d+)(.+)/i". Can I?

    Now it looks that I can use only "refs/heads/*" pattern, but it will match master and some not required branches too (really it will match to all branches and it leas to some overhead).

    Related issue: http://youtrack.jetbrains.com/issue/TW-20529

    1. Regexps are not supported yet. But you can use any prefix and suffix you want, e.g. you can use refs/heads/SOMEPRJ-123_* or refs/heads/*@teamcity as a pattern. Also please be aware of the issue TW-16964 : if you have hundreds of long-lived branches monitored by this trigger, performance can degrade over time (especially for git roots over ssh). So it is better to cleanup unused branches.

      1. What does @teamcity placeholder mean? Username teamcity?

        And some more description about my case: I'm researching "Branch Remote Run" to include it in development workflow. Right now I'm trying to get it work on main repository which has branches as many as active tasks in that time (I mean that we have some "cleanup policy" for branches in other words we have a case when branch is removed from origin), possible I can reduce branches count but it will be not less then 300 I think. And later I'll include some another git repos (at least 20) with really small amount of branches and they will be in other projects / builds in TeamCity.

        And other suggest: Is there a way to tell teamcity using it's API in which exact branch I need to run build?

        I mean that I want use it not like "listen changes and run build" but like "allow use configured build with git master branch to run pre-tested commits from other branchs using button in IDE or shell script".

        1. @teamcity has no special meaning, it is just a suffix, some teams inside jetbrains use this naming convention to mark branches for remote-run trigger.

          Branch remote-run trigger runs builds for all the branches matched the pattern. To run build for the specific branch you can do the following:

          • create a config parameter branch.name, with the value master
          • put a reference to this parameter in the Ref field of the git VCS root
          • now you can a build with changed value of branch.name parameter from web UI or from IDE, more details here .
          • you can also trigger such a build from script
          1. Thx, seems that such case can resolve my problems.

          2. But why don't allow developer use Remote Run for other branches in one build configuration.

            I mean that I have Build Configuration for master in Team City and I want to be able use that Build Configuration with Remote Run from PHPStrom when other (not master) branch is checkouted in IDE.

            1. In the current implementation, there should be one main branch (master in your case). TeamCity calculates changes in the personal builds relative to this branch, also if you have several VCS roots and only one of them has personal branch - in the other VCS root we will take the main branch. What's why we need it.

  2. Are there any plans to support Perforce with branch remote-runs, e.g. via the new lightweight "task branches"?

  3. Is there only commandline support for this?, no support via the TeamCity IDE plugin for VisualStudio?