Blogroll How-To's

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.

Comments below can no longer be edited.

32 Responses to Building GitHub pull requests with TeamCity

  1. Avatar

    Dariel says:

    August 20, 2019

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

    • Avatar

      Anton Arhipov says:

      August 21, 2019

      Yes. You can set the branch specification in the vcs trigger like this: +:pull/*

  2. Avatar

    Carl-Erik Kopseng says:

    August 21, 2019

    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.

    • Avatar

      Anton Arhipov says:

      August 21, 2019

      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. Avatar

    Chris Blyth says:

    September 3, 2019

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

    • Avatar

      Anton Zamolotskikh says:

      September 3, 2019

      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.

      • Avatar

        Dennis Doomen says:

        December 12, 2019

        Do you have any sources for this information? We’ve been relying on the `pull/*/merge` thing for years, but have observed some weird behavior occasionally.

        • Avatar

          Anton Zamolotskikh says:

          December 13, 2019

          Hi Dennis, we know when the branches get updated based on our experience with GitHub, but this is not described anywhere in my knowledge.

          As for this feature being not officially supported, we communicated with GitHub some time ago and that was their response. You can try to clarify it with them.

          We have implemented support for these merge branches in the Pull Requests build feature but had to disable it for these reasons.
          You can switch this functionality on by setting an internal property teamcity.pullRequests.buildBranchFilterEnabled to true.

          A word of caution: this functionality is not officially supported by TeamCity, it is not guaranteed that it reliably works and we might remove or alter it in the future versions of TeamCity.

  4. Avatar

    Anton says:

    October 18, 2019

    How we can trigger only by pull requests when target branch name is started with “release”?
    Does Pull Request Filtering – Filtering by target branch support regex? For example: refs/heads/release-*

    • Avatar

      Anton Arhipov says:

      October 21, 2019

      Hi! Currently, the target branch must be a full name. No regex definitions supported yet.

      • Avatar

        Francois Bester says:

        January 13, 2020

        This is a major bummer.
        Seems like an oversight for such a simple feature.

  5. Avatar

    Mariano says:

    October 22, 2019

    Hi Anton, thanks for this info.

    Is it possible to close the PR if build fails?


    • Avatar

      Anton Arhipov says:

      November 8, 2019

      Hello Mariano. There’s no such feature for the pull requests integration.

      In theory, it would be possible to close the PR by executing a curl command towards GitHub’s API via CLI runner in TeamCity. However, it means that you’d need to get a build status somehow – possible via TeamCity’s REST API. So it is possible, but it would require some custom scripting to achieve it.

  6. Avatar

    Lior Tal says:

    November 11, 2019

    I configured this like this post instructd, but i did not get any build triggered.

    Are there any logs or anything useful to diagnose this ?

    • Avatar

      Anton Arhipov says:

      December 10, 2019


      There’s a few things to look at:

      1) Can you run “Test connection” in the Pull Requests build feature configuration? Does it work fine?

      2) Does TeamCity detect the changes for the branches that you have configured in the VCS root? (Should be visible in the build configuration overview page)

      3) Have to check, if the pull request is submitted from the fork or from the same repository; was the PR submitted by the user that belongs to the same organization (as configured in the build feature) or it is an external contributor..

      • Avatar

        Magnus says:

        January 29, 2020

        Does it support building PR:s that come from forks? This is typical for an open source projects where outside contributors are not allowed to create branches on the main repository.

        A question related to this: Can the build be conditioned on having an approval on the PR? Or that the build needs to be manually triggered from the PR view by a maintainer? The reason I ask is that I don’t want anyone to be able to just fork my repo, open a PR and have that PR be built my Teamcity instance. They could have added malicious code that runs as part of the build process.

  7. Avatar

    Lior Tal says:

    November 18, 2019

    In the post it is said that : “Hence, it is better to avoid adding +:* or +:refs/pull/*”
    Can you tell why exactly ?

    Also, why does the commit status publisher feature require a push permission in the access token ?

    • Avatar

      Anton Arhipov says:

      December 10, 2019

      As the sentence prior to the statement says: “It is possible to configure the VCS root to match the incoming pull request branches and TeamCity will start the builds automatically.”

      So if you use +:* , the incoming PR branches will be detected and the builds will automatically start. That is a security issue – you better not start the builds automatically for the PRs that come from the external contributor.

  8. Avatar

    David Vargas says:

    January 7, 2020

    Is it possible to get the logical branch name? i.e. have my build just be tagged `51` for `pull/51` ?

  9. Avatar

    Prashant says:

    January 23, 2020

    I am not able to use teamcity.pullRequest.* parameters in my build. Is it not possible to get pull request number?

    • Avatar

      Vadym Kononenko says:

      February 14, 2020

      Me too.

      Once I put %teamcity.pullRequest.number% and into my Command Line step TC adds them to “Configuration Parameters” like:
      teamcity.pullRequest.number Edit undeletable Edit undeletable
      and doesn’t allow to build this Job because of ‘none agent is matched to this job’.

      After I remove %% chars – job reacts to MR successfully.

    • Avatar

      Anton Zamolotskikh says:

      February 14, 2020

      Hi, few questions (to Vadym below as well):
      – what version of TeamCity are you trying it on?
      – do you have the Pull Requests build feature configured in the same configuration where you refer to these parameters?
      – where exactly are you using these references? (build steps? something else?)

  10. Avatar

    Bulat says:

    January 30, 2020

    Hi! I am trying to compose regular build configs (‘build’ and ‘test’) with a composite build config. The idea is the next: ‘build’ and ‘test’ can see all changes in a repo. They have no triggers. Also, there is composite build config called ‘PR’ which has
    1) Pull request build feature
    2) VCS trigger ‘+:pull/*’
    3) snapshot dependency to ‘build’ and ‘test’

    When I create new Pull request in GitHub it triggers ‘PR’ build config which triggers ‘build’ and ‘test’. The problem is that dependency builds start building master branch. Even if I set in root VCS Branch specification ‘+:*’ rule for ‘build’ and ‘test’

    • Avatar

      Anton Zamolotskikh says:

      January 30, 2020

      Hi Bulat,

      You have to add the pull requests build feature to all three configurations. Please let us know if this doesn’t work for some reason.

      • Avatar

        Bulat says:

        January 30, 2020

        Yes, it has worked. I have found this solution earlier but was thinking that it is not supposed way of how TeamCity should work. I mean pull request branch was already visible to ‘build’ and ‘test’, right? Why I have to additionally use PR build feature?

        Overall it seems straightforward solution to me that dependency build has to run on depended build’s branch.

        • Avatar

          Anton Zamolotskikh says:

          February 10, 2020

          Basically pull request build feature extends the branch spec in context of a build configuration, but not for all builds in a build chain that use this VCS root.

  11. Avatar

    Stefan F says:

    February 5, 2020

    Is it possible to support multiple repositories with the pull request feature?

    We have builds using three git repos and the ‘feature branch’ thing which selects same branch name with
    fallback to default between the repos works fine.

    What I want to do with the pull requests are to verify them by building ‘refs/pull-requests/###/merge’
    (### is some number)
    Earlier comment mention that setting teamcity.pullRequests.buildBranchFilterEnabled should enable build/verification of the merge branch.

    The issue/challenge is to get the build to use related pull requests between vcs repos.
    repo A: Pull request 37 feature/ABC-321 -> dev ( refs/pull-requests/37/merge )
    repo B: no branch nor pull req, should use default ‘dev’ ( dev )
    repo C: Pull request 85 feature/ABC-321 -> dev ( refs/pull-requests/85/merge )

    I’d like the pull request verification build to use the branches inside parenthesis above.

    (yes, there can be a race issue depending on which order the PRs are created but the second
    build should be ok using the related pull requests)

    In short, can we ‘connect’ pull requests between repos in a similar way as the feature branch by name mechanism.
    Need to look at source and destination branch of the pr.

    • Avatar

      Anton Zamolotskikh says:

      February 10, 2020

      Hi Stefan, there is a related (but different) feature request with quite an extended discussion about this in our issue tracker:, we will be grateful if you add your use case to it.

      It would be also quite interesting if you have any suggestion in respect to a logical branch name associated with such builds that use differently named VCS branches in different VCS roots. Thanks!

      • Avatar

        Stefan F says:

        February 17, 2020

        I’ll have a look, thanks /stefan

  12. Avatar

    Herby says:

    February 6, 2020

    Do you plan to support pull requests in Gogs/Gitea?

    • Avatar

      Anton Zamolotskikh says:

      February 10, 2020

      Hi Herby,

      We were not yet considering implementing such support for Gogs/Gitea. You can of course create a feature request in our issue tracker:

      We will considering implementing Gogs/Gitea support if more users vote for such an issue.

      We are considering making pull requests more of a first class citizen in TeamCity though. There are no specific plans in respect to TeamCity version yet, and there was no feature request about it in our tracker, but I have made one now: When (and if) this is done it may become significantly easier to develop a third party plugin supporting Gogs/Gitea.

Discover more