Building GitHub pull requests with TeamCity

The support for pull requests in TeamCity was first implemented for GitHub as an external plugin. Starting with TeamCity version 2018.2 the plugin is bundled in the distribution package with no need to install the external plugin. The functionality has since been extended in version 2019.1 to support GitLab and BitBucket Server.

In this blog post, we will share some tips for building GitHub pull requests in TeamCity. First, there are a few things you need to know about when configuring the VCS root in regards to pull request handling. Next, we’ll cover Pull Requests and the Commit Status Publisher build features. And finally, we’ll see how it all comes together when building pull request branches.

Setting up a VCS root

First, let there be a VCS root in a TeamCity project. We can configure the VCS root in Build Configuration Settings | Version Control Settings and click Attach VCS root.

When setting up the VCS root we have to make sure that the branch specification does not match the pull request branches.


The branch specification in the screenshot above includes a +:refs/heads/feature-* filter. This means that any branch in the GitHub repository that starts with feature-* will be automatically detected by this VCS root. A pull request in GitHub is a git branch with a specific naming convention: refs/pull/ID/head, whereas the ID is the number of the pull request submitted to the repository.

It is possible to configure the VCS root to match the incoming pull request branches and TeamCity will start the builds automatically. However, you might want to restrict the automatic build triggering for these branches. Hence, it is better to avoid adding +:* or +:refs/pull/* patterns to the branch specification of a VCS root. Instead, we can use the Pull Requests build feature to gain more control over the incoming pull requests.

Configuring Pull Requests build feature

Pull request support is implemented as a build feature in TeamCity. The feature extends the VCS root’s original branch specification to include pull requests that match the specified filtering criteria.

To configure the pull requests support for a build configuration, go to Build Configuration Settings | Build Features, click Add build feature, and select the Pull Requests feature from the dropdown list in the dialog.


We can then configure the build feature parameters: select the VCS root, VCS hosting type (GitHub), credentials, and filtering criteria.


The Pull Requests build feature extends the branch specification of the related VCS root. As a result, the full list of branches that will be visible by the VCS root will include the following:

  • The default branch of the VCS root
  • Branches covered by the branch specification in the VCS root
  • Service-specific open pull request branches that match the filtering criteria, added by Pull Requests build feature

For GitHub’s pull request branches we can configure some filtering rules. For instance, we can choose to only build the pull requests automatically if they are submitted by a member of the GitHub organization.

In addition to this, we can also filter the pull requests based on the target branch. For instance, if the pull request is submitted to refs/head/master then the pull request branch will be visible in the corresponding VCS root. The pull request branches whose target branch does not match the value specified in the filter will be filtered out.

Publishing the build status to GitHub

For better transparency in the CI workflow, it is useful to have an indication of the build status from the CI server next to revision in the source control system. So when we look at a specific revision in the source control system we can immediately tell if the submitted change has been verified at the CI server. Many source control hosting services support this functionality and TeamCity provides a build feature to publish the build status into external systems, the Commit Status Publisher.


The build status indication is useful when reviewing the pull requests submitted to a repository on GitHub. It is advisable to configure the Commit Status Publisher build feature in TeamCity if you are working with pull requests.

Triggering the builds

The Pull Requests build feature makes the pull request branches visible to the related VCS root. But it does not trigger the builds. In order to react to the changes detected by the VCS root we need to add a VCS trigger to the build configuration settings.

To add the VCS trigger to a build configuration, go to Build Configuration Settings | Version Control Settings, click Add new trigger, and select the VCS trigger from the list.


The default value in the branch filter of the VCS trigger is +:*. It means that the trigger will react to the changes in all the branches that are visible in the VCS roots attached to the same build configuration. Consequently, when a pull request is submitted, the trigger will apply and the build will start for the pull request branch.

Building pull requests

Once the Pull Requests build feature is configured we can try submitting a change to a GitHub repository:


When the new pull request is created, we can choose the branch in the target repository. This is the branch we can filter in the Pull Requests build feature settings in TeamCity.


Once the pull request is submitted, TeamCity will detect that there’s a new branch in the GitHub repository and will start the build.


The build overview page in TeamCity provides additional details about the pull request.


The build status is also published to the GitHub repository by the Commit Status Publisher:


Here is a short screencast demonstrating the process above:


Now the puzzle pieces are coming together. The Pull Requests build feature extends the branch specification of the VCS root to match the pull request branches. The VCS trigger detects that a new pull request was submitted to the GitHub repository and triggers the build. Once the build is complete, the Commit Status Publisher sends the build status back to GitHub.

About Anton Arhipov

Developer Advocate at JetBrains
This entry was posted in Blogroll, How-To's and tagged , , , , , . Bookmark the permalink.

6 Responses to Building GitHub pull requests with TeamCity

  1. Dariel says:

    Above, where it mentions a branch filter of +:*
    can it be scoped to +:refs/pulls/* to only trigger on pull requests?

  2. Carl-Erik Kopseng says:

    Is it possible to report multiple steps? CircleCI and similar services can expose which step of the process they are currently at (of several) and indicate where it failed.

    I am assuming I could set up one main pull request build triggered by CVS changes, and some other builds (“steps”) that somehow depended on this. Not totally sure how to do this upstream/downstream build thing, though, and if it would work.

    • Anton Arhipov says:

      Sure! A build configuration can include multiple steps. While the build is running TeamCity displays it in the status for the build. If some step in the middle of the sequence fails, you will see the corresponding message in the build overview with a link that takes you to the correct place in the build log so you can investigate what happened.

      What you are probably looking for is the ability to connect multiple build configurations into a build chain. In TeamCity you can configure a build configuration to depend on the other build configuration. See snapshot dependencies:

  3. Chris Blyth says:

    Is it possible to get TeamCity to build the merge of the pull request and not the HEAD?

    • Anton Zamolotskikh says:

      Hi Chris,

      GitHub does expose refs/pull//merge branches for pull requests, but there are two problems with it:

      – currently these branches don’t get updated until somebody actually went to the PR page or requests a PR information via REST or GraphQL API;

      – GitHub states that this is only an internally functionality, that is not guaranteed to be working in the future.

      For these reasons Pull Requests plugin doesn’t support these branches. You can of course always configure your branch specs (e.g. refs/(pull/*/merge)) to match them, but this way you will not be using the Pull Request build feature functionality, such as showing PR information in TeamCity UI and no filtering of any kind (i.e. by target branch or author’s role) will be applied.

Leave a Reply

Your email address will not be published. Required fields are marked *