Pull Requests

The Pull Requests build feature enhances TeamCity integration with pull (merge) requests in GitHub, Bitbucket Server, Bitbucket Cloud, GitLab, Azure DevOps, and JetBrains Space repositories.

Common Information

Adding the Pull Requests feature to a build configuration allows you to:

View pull request branches and their pending changes on the build configuration's overview page.
View pull request's details on the Overview tab of the build results page.
In the case of a draft pull request, the icon is grayed-out and the Draft status appears before the pull request number:
Set up specific criteria that govern which pull requests to monitor. You can filter pull requests by their authors, target and origin branches.
Note that branch filters for the Pull Requests build feature accept fully qualified VCS branch names only, regardless of how these branches are displayed in TeamCity UI.
For example, if a user creates a new pull request by executing the gh pr create --base source-branch --head master --assignee "@johndoe" GitHub CLI command, use refs/heads/source-branch and/or refs/heads/master names to point the Pull Requests feature to the related target/source branches. Omitting refs/heads/ and using shortened logical branch names ([+|-]:source-branch, [+|-]:master, [+|-]:pull/10) will result in faulty filters that do not target required branches.
Set up a workflow in which developers work in their local branches and TeamCity does not waste resources building these changes unless they are sent as a pull (merge) request (see the Interaction with VCS Roots section).

The Pull Requests feature does not automatically trigger new builds against pull (merge) request branches. To assess changes from pull request branches before they are merged into the main codebase, add a VCS trigger that targets required branches (for example, refs/pull/* for GitHub). New build configurations created in TeamCity UI already include a trigger with the +:* specification, which allows TeamCity to build changes from pull (merge) request branches.

If your build configuration targets a public repository where non-trusted users can push commits or create pull (merge) requests, building these changes means TeamCity can execute malicious code introduced in them. For example, TeamCity may handle a harmful service message sent from the source code or apply altered project settings from modified .teamcity folder files.

To prevent this from happening, do not configure VCS triggers and Pull Requests build features in such a manner that builds with unverified pull (merge) request changes can start automatically. Instead, either start new builds manually after you inspect and verify incoming changes, or set up Untrusted Builds to require additional review for external pull requests.

See this section for more information about potential damage caused by users who can modify repository code: Security Notes.

If your project targets a GitHub or GitLab repository, you can automate your setup even further by letting TeamCity build pull request branches and merge those requests that yield successful builds. To do this, add the Automatic Merge build feature in addition to Pull Requests.

Interaction with VCS Roots

The Pull Requests feature extends the original branch specification of VCS roots attached to the current build configuration. As such, branch specifications of a VCS root must not contain patterns that match pull request branches to avoid ambiguous and unexpected behavior.

If you want to build only pull requests, clear the VCS root's branch specification.

object MyRepoRoot : GitVcsRoot({
    name = "MyRoot"
    url = "https://github.com/username/reponame"
    branch = "refs/heads/main"
    // the "branchSpec = ..." parameter is missing
})

The sample below illustrates how to correctly set up your TeamCity project so that the root branch specifications and the Pull Requests feature complete each other to implement the following workflow:

TeamCity tracks only main, production, and sandbox branches, as well as all branches that start with "release-" (for example, release-2077.02).
Developers can create local branches and work with them without any exposure to TeamCity.
When a developer is ready to publish their changes, they can create a request to merge their commits from a personal (untracked) into core (tracked) branch. This will result in a new pull branch (for example, refs/pull/54 on GitHub). The Pull Requests feature will detect this new branch, making it possible to build and test changes in TeamCity before they are merged.
Due to feature's Filter by author setting, TeamCity ignores similar refs/pull/<Int> branches created for unauthorized (external) users' requests.

project {
    vcsRoot(MyRepoRoot)
    buildType(Build)
}

object Build : BuildType({
    name = "Build"
    vcs { root(MyRepoRoot) }

    // ...

    features {
        pullRequests {
            vcsRootExtId = "${MyRepoRoot.id}"
            provider = github {
                authType = vcsRoot()
                filterAuthorRole = PullRequests.GitHubRoleFilter.MEMBER
            }
        }
    }
})

object MyRepoRoot : GitVcsRoot({
    name = "MyRoot"
    url = "https://github.com/username/reponame"
    branch = "refs/heads/main"
    branchSpec = """
        refs/heads/main
        refs/heads/production
        refs/heads/sandbox
        refs/heads/release-*
    """.trimIndent()
})

VCS-specific settings

GitHub Pull Requests

This feature supports GitHub and GitHub Enterprise. It monitors builds only on the refs/pull/*/head branch.

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	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.
	GitHub App access token	A non-personal short-lived token issued via the GitHub App. This option is available only when the VCS Root setting points to the specific VCS root, and this root is configured using a GitHub App connection.
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 source branch		Define the branch filter to monitor pull requests only on source branches that match the specified criteria. If left empty, no filters apply.
By target branch		Define the branch filter to monitor pull requests only on target branches that match the specified criteria. If left empty, no filters apply.
Ignore Drafts		By default, the Pull Requests build feature loads the GitHub draft pull requests information and runs builds on draft pull requests. The build page displays a grayed-out icon and the Draft status next to the merge request number. Check the box to ignore GitHub draft pull requests. TeamCity will not load the draft pull request information until its status changes.
Server URL		Specify a GitHub URL for connection. If left empty, the URL will be extracted from the VCS root fetch URL.

Bitbucket Server/Data Center Pull Requests

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

Parameter	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 uses an SSH fetch URL or employs anonymous authentication. Username/password — Specify a username and password for connection to Bitbucket Server/Data Center. You can submit an access token instead of the password. The token should have Read permissions for projects and repositories. Refreshable access tokens are short-lived tokens acquired by TeamCity from a required VCS provider via existing OAuth connections (as opposed to static PAT tokens issued manually by users on a VCS hosting side). See the following article for more information on generating and using refreshable tokens: Manage Refreshable Access Tokens.
Username/password	Specify a username and password for connection to Bitbucket Server. You can submit an access token instead of the password. The token should have Read permissions for projects and repositories.
By source branch	Define the branch filter to monitor pull requests only on source branches that match the specified criteria. If left empty, no filters apply.
By target branch	Define the branch filter to monitor pull requests only on target branches that match the specified criteria. If left empty, no filters apply.
Server URL	Specify a Bitbucket URL for connection. If left empty, the URL will be extracted from the VCS root fetch URL.
Use pull request branches	This option is intended for backward compatibility only. Enables detection of officially unsupported Bitbucket pull request branches (pull-requests/*) instead of source branches. Be careful: new builds might be triggered for changes committed within the last hour after switching.

Bitbucket Cloud Pull Requests

Since Bitbucket Cloud does not create dedicated branches for pull requests, this build feature monitors directly source branches in a source repository (forks are not supported).
If more than one pull request is submitted from the same source branch at the moment of the build start, TeamCity will display all these requests in the build results. However, only commits from the open PRs matching the filtering criteria will be displayed as Changes of the build.

Note that the branch specification of the VCS root must not contain patterns matching pull request branches.

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

Setting	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 uses an SSH fetch URL or employs anonymous authentication. Username/password — Specify a username and password for connection to Bitbucket Cloud. We recommend using an app password with the Pull Requests \| Read scope. Refreshable access tokens are short-lived tokens acquired by TeamCity from a required VCS provider via existing OAuth connections (as opposed to static PAT tokens issued manually by users on a VCS hosting side). See the following article for more information on generating and using refreshable tokens: Manage Refreshable Access Tokens. Permanent Access Token — Enter a Bitbucket Repository Access Token, Project Access Token, or Workspace Access Token to configure long-lived access to a repository, workspace, or project. The token must be configured with the Pull Requests \| Read scope.
By target branch	Define the branch filter to monitor pull requests only on branches that match the specified criteria. If left empty, no filters apply.

Setting

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 uses an SSH fetch URL or employs anonymous authentication.
Username/password — Specify a username and password for connection to Bitbucket Cloud. We recommend using an app password with the Pull Requests | Read scope.
Refreshable access tokens are short-lived tokens acquired by TeamCity from a required VCS provider via existing OAuth connections (as opposed to static PAT tokens issued manually by users on a VCS hosting side). See the following article for more information on generating and using refreshable tokens: Manage Refreshable Access Tokens.
Permanent Access Token — Enter a Bitbucket Repository Access Token, Project Access Token, or Workspace Access Token to configure long-lived access to a repository, workspace, or project. The token must be configured with the Pull Requests | Read scope.

By target branch

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

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.

This feature monitors builds only on the refs/merge-requests/*/head branch.

The following parameters are available for the GitLab hosting type:

Parameter	Description
Authentication Type	Use VCS root credentials — TeamCity will try to extract login credentials or access token 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. Personal Access Token — Use a personal access token issued in GitLab. It must have either the `api` scope. Refreshable access tokens are short-lived tokens acquired by TeamCity from a required VCS provider via existing OAuth connections (as opposed to static PAT tokens issued manually by users on a VCS hosting side). See the following article for more information on generating and using refreshable tokens: Manage Refreshable Access Tokens.
By source branch	Define the branch filter to monitor merge requests only on source branches that match the specified criteria. If left empty, no filters apply.
By target branch	Define the branch filter to monitor merge requests only on target branches that match the specified criteria. If left empty, no filters apply.
Ignore Drafts	By default, the Pull Requests build feature loads the GitLab draft merge requests information and runs builds on draft merge requests. The build page displays a grayed-out icon and the Draft status next to the merge request number. Check the box to ignore GitLab draft merge requests. TeamCity will not load draft merge request information and a merge request is ignored until its status changes to non-draft.
Server URL	Specify a GitLab URL for connection. If left empty, the URL will be extracted from the VCS root fetch URL.

Azure DevOps Pull Requests

This feature monitors builds only on the refs/pull/*/merge branch.

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.

Authentication Settings

Personal Access Token — a static token that you can issue in your Azure DevOps account settings. Your issued token should have the Code (read) scope to allow Pull Requests to retrieve required information.
Refreshable access tokens are short-lived tokens acquired by TeamCity from a required VCS provider via existing OAuth connections (as opposed to static PAT tokens issued manually by users on a VCS hosting side). See the following article for more information on generating and using refreshable tokens: Manage Refreshable Access Tokens.

Pull Request Filtering

By source branch — the branch filter to monitor pull requests only on source branches that match the specified criteria. If left empty, no filters apply.
By target branch — the branch filter to monitor pull requests only on target branches that match the specified criteria. If left empty, no filters apply.

Other Settings

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

JetBrains Space Merge Requests

This feature monitors merge requests directly in the source branches of an origin repository.
If more than one merge request is submitted from the same source branch, TeamCity will display all these requests in the build results. However, only commits from the open requests matching the filtering criteria will be displayed as Changes of the build.

The following parameters are available for the JetBrains Space hosting type:

Parameter	Description
Connection	Choose a preconfigured connection to JetBrains Space.
By target branch	Define the branch filter to monitor merge requests only on branches that match the specified criteria. If left empty, no filters apply.

If you want to run several parallel builds to pretest a request before merging it, the best solution is to:

Create a composite build configuration and attach your JetBrains Space VCS root with an empty branch specification to it.
Add the composite build configuration at the end of the build chain by configuring its snapshot dependencies on parallel builds with tests.
Add the Pull Requests feature to each build configuration of the chain so that all builds can detect changes in a merge request branch. You can preconfigure all settings in a build configuration template and then create these build configurations based on it.
In the composite build configuration settings:
- Add a VCS trigger to automatically run builds on changes detected in the merge request branch.
- Add the Commit Status Publisher feature to send the build statuses to the commit details in JetBrains Space.
  
  If you want other builds of the chain to report their statuses to JetBrains Space (for example, deployment or integration testing builds), add the Commit Status Publisher feature to the corresponding build configurations.

After that, TeamCity will automatically run builds on changes in a merge request branch submitted to your JetBrains Space repo and publish build statuses to the merge request timeline in Space:

To protect a JetBrains Space branch from unverified merge requests, you can also configure Quality Gates in your repository settings. If you set a TeamCity build as an external check, JetBrains Space will require the build on a merge request to finish successfully before allowing this request to be merged.

See known issues with processing JetBrains Space merge requests here.

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 workflow for the web-app build configuration in TeamCity:

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 Settings of the GitHub user that has access rights to the web-app repository
- Test the connection and, if successful, click Create.
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 empty 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.
Add a VCS trigger to the build configuration.

With this integration in place, whenever a member of your GitHub organization sends a pull request to the master branch, TeamCity does the following:

Detects the pull request sent to the master branch.
Runs the web-app build configuration: collects sources, builds and tests the app according to your predefined build steps.
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).

Pro Tips

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.
If you want to run a whole build chain on a pull request, remember to add the Pull Requests feature to each build configuration of the chain. To simplify this procedure, you can set everything in a build configuration template and then create these build configurations based on it.

Troubleshooting

TeamCity writes events related to the Pull Requests build feature to the teamcity-pull-requests.log file. Apply the "debug-pull-requests" preset to include DEBUG-level events to this log.

Last modified: 13 November 2024