TeamCity 2020.1 Help

Pull Requests

The Pull Requests build feature lets you automatically load pull request (or merge requests in case of GitLab) information and run builds on pull request branches in GitHub, Bitbucket Server, GitLab, and (since version 2020.1) Azure DevOps.

The feature extends the original branch specification of the VCS roots, attached to the current build configuration, to include pull requests that match the specified filtering criteria. It monitors builds only on head branches:

  • For GitHub: refs/pull/*/head

  • For Bitbucket Server: refs/pull-requests/*/from

  • For GitLab: refs/merge-requests/*/head

  • For Azure DevOps: refs/pull/*/merge

In case with Azure DevOps, TeamCity detects requests on a merge branch. In other VCSs, it checks out the code from the source branch.

If you configure a VCS trigger for your build configuration, TeamCity will automatically run builds on changes detected in the monitored branches.

You can find the pull request's details displayed on the Overview tab of the Build Results:

Pull request details

When adding this build feature, you need to specify a VCS root and select a VCS hosting type.

The build feature parameters depend on the selected VCS hosting type.

See the example on how to set up TeamCity to run builds on pull requests.

VCS-specific settings

GitHub Pull Requests

TeamCity supports GitHub and GitHub Enterprise.

The following parameters are available for the GitHub hosting type:

Parameter

Option

Description

Authentication Type

Use VCS root credentials

TeamCity will try to extract username/password credentials or a personal access token/ x-oauth-basic from the VCS root settings if the VCS root uses HTTP(S) fetch URL.

This option will not work if the VCS root employs anonymous authentication or SSH.

For a GitHub Enterprise repository, only the personal access token/ x-oauth-basic pair will work.

Access token

The ' Token' field appears.

Use a personal access token or obtain a token through an OAuth connection. It must have either the public_repo (for public repositories) or repo (for private repositories) scope.

By authors

The filter applies to public repositories only.

Members of the same organization

Only detects pull requests submitted by members of the same organization in GitHub.

Members and external collaborators

Only detects pull requests submitted by members of the same organization and external collaborators in GitHub.

Everybody

Detects all pull requests. Be aware that selecting this option may allow arbitrary users to execute malicious code on your build agents.

By target branch

Define the branch filter to monitor pull requests only on branches that match the specified criteria. If left blank, no filters apply.

Server URL

Specify a GitHub URL for connection.

If left blank, the URL will be extracted from the VCS root fetch URL.

Bitbucket Server Pull Requests

The following parameters are available for the Bitbucket Server hosting type:

Parameter

Options

Description

Authentication Type

Use VCS root credentials

TeamCity will try to extract username/password credentials from the VCS root settings if the VCS root uses HTTP(S) fetch URL.

This option will not work if the VCS root employs anonymous authentication.

Username/password

The ' Username' and ' Password' fields appear.

Specify a username and password for connection to Bitbucket Server.

By target branch

Define the branch filter to monitor pull requests only on branches that match the specified criteria. If left blank, no filters apply.

Server URL

Specify a Bitbucket URL for connection.

If left blank, the URL will be extracted from the VCS root fetch URL.

GitLab Merge Requests

TeamCity processes GitLab merge requests similarly to how it processes pull requests in other hosting services. Currently, TeamCity detects only merge requests submitted after this build feature is enabled.

The following parameters are available for the GitLab hosting type:

Parameter

Description

Access token

Use a personal access token for connection. The token must have the api scope.

By target branch

Define the branch filter to monitor merge requests only on branches that match the specified criteria. If left blank, no filters apply.

Server URL

Specify a GitLab URL for connection.

If left blank, the URL will be extracted from the VCS root fetch URL.

Azure DevOps Pull Requests

In case with Azure DevOps, TeamCity detects requests on a merge branch – not on the pull request itself as with other VCSs. Each build will be launched on a virtual branch showing an actual result of the build after merging the PR. Thus, the build will contain both the commit with changes and the virtual merge commit.

Note that the feature ignores Azure DevOps draft pull requests.

The following parameters are available for the Azure DevOps hosting type:

Parameter

Description

Access token

Use a personal access token for connection. The token must have the Code (read) scope.

By target branch

Define the branch filter to monitor pull requests only on branches that match the specified criteria. If left blank, no filters apply.

Project URL

Specify a project URL for synchronization with the remote Azure DevOps server. This field is recommended for on-premises Azure DevOps installations. If left blank, the URL will be composed based on the VCS root fetch URL.

Predefined build parameters for pull requests

TeamCity provides multiple predefined build parameters that expose valuable information on pull requests for builds with the enabled Pull Requests feature:

teamcity.pullRequest.number //pull request number teamcity.pullRequest.title //pull request title teamcity.pullRequest.source.branch //VCS name of the source branch; provided only if the source repository is the same as the target one teamcity.pullRequest.target.branch //VCS name of the target branch

You can use these parameters in the settings of a build configuration or in build scripts.

Pull Requests workflow example

Let's say you have the following environment set up:

  • public GitHub repository web-app with the default branch master

  • TeamCity project
    • build configuration web-app that uses files from the web-app repository to build a web application

The members of your organization propose changes to the sources by sending pull requests to the master branch, and you want these changes to be automatically built and tested in TeamCity before you merge them.
TeamCity can detect each pull request sent to the master branch and build the web application based on the updated sources.

To configure the described pipeline for the web-app build configuration in TeamCity:

  1. Add a VCS root to the build configuration:
    • Go to Build Configuration Settings | Version Control Settings and click Attach VCS root.

    • Configure the root parameters:

      • Type of VCS: Git

      • VCS root name: <unique_root_name>

      • Fetch URL: <GitHub_repository_URL>

      • Default branch: the branch to be monitored; by default, refs/heads/master (read more about feature branches)

      • Branch specification: a filter for additional branches to be monitored (for example, +:refs/heads/*)

      • Authentication parameters of the GitHub user that has access rights to the web-app repository

    • Test the connection and, if successful, click Create.

  2. Add the Pull Requests build feature to the build configuration:
    • Go to Build Configuration Settings | Build Features and click Add build feature.

    • Configure the feature parameters:
      • VCS Root: the VCS root created at Step 1

      • VCS hosting type: GitHub

      • Authentication type: Use VCS root credentials, or select Access token to use a GitHub token instead

      • Pull Requests filtering:
        • By authors: Members of the same organization

        • By target branch: leave blank to apply no filters and monitor all new pull requests in the repository, or explicitly specify the target branch (in this example, master)

    • Test the connection and, if successful, click Save.

That's it! Now, whenever a member of your GitHub organization sends a pull request to the master branch, TeamCity acts as follows:

  1. Detects the pull request sent to the master branch.

  2. Runs the web-app build configuration: collects sources, builds and tests the app according to your predefined build steps.

  3. Displays information about the processed pull request on the build configuration Overview page. You can instantly see the pull request status (1) and refresh the information about its state (2).

    Pull Request information in Build Overview

Pro Tip

You can automate your setup further, so TeamCity:

  • sends a build status back to GitHub after the build finishes, with the Commit Status Publisher build feature

  • merges the pull request in GitHub if the build finishes successfully, with the Automatic Merge build feature

Last modified: 17 September 2020