Branch Remote Run Trigger

The 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. Finished personal builds are listed in the build history, but only for the users who initiated them.

At the moment, the branch remote run trigger supports only Git and Mercurial VCSs.

For non-personal builds off branches, see Working with Feature Branches. When a branch specification is configured for a VCS root, the branch remote run trigger only processes branches not matched and not excluded by the specification.

Triggering Settings

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 (that is if you no longer need the branch, you would need to delete the branch using regular version control methods).

By default, TeamCity triggers a personal build for the user detected in the last commit of the branch. You might also specify a 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, the 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).

To be able 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

Git

% cd <your_local_git_repo>
% git branch
* master
% git checkout -b my_feature
Switched to a new branch 'my_feature'
//code, commit; code, commit
% git push origin +HEAD:remote-run/my_feature

With the default pattern (refs/heads/remote-run/*), the git branch -r command 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>.

Mercurial

% cd <your_local_hg_repo>
% hg branch
default
% hg branch remote-run/my_feature
marked working directory as branch remote-run/my_feature
//code, commit; code, commit
% hg push -b remote-run/my_feature --new-branch

Limitations

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 one personal build with changes per each VCS root.

Triggered Build Customization

The Build Customization tab of a trigger's settings allows configuring custom parameters of builds started by this trigger. Similarly to the Run Custom Build dialog, it lets you override values of build parameters and choose if the checkout directory should be cleaned before the build.

On this tab, you can customize the value of any parameter used in the current build configuration. Or, you can add a new parameter, and it will be available only in builds started by this trigger. If the current build has snapshot dependencies on other builds, such a parameter can also be used to override a certain property of a dependency build configuration: use the reverse.dep.<dependencyBuildID>.<property> syntax for this.

Note that if you redefine a build parameter inside a trigger and then delete the original parameter in Parameters, its redefined value will be converted to the trigger's own plain-text parameter. This is crucial to consider when customizing secure values, as they are only concealed if stored with the "Password" type and will become readable if converted to plain text.

TeamCity allows solving similar tasks in multiple ways, and in some cases it is still preferable to create different build configurations. For example, if there are too many custom runs in the same configuration, it might be harder for TeamCity to predict the exact duration of each build. If you need to trigger builds with numerous different parameters, we suggest that you create a build configuration template and use it as a blueprint for several configurations, each with its own parameters.

Last modified: 28 March 2022