Pull Requests

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:

Authentication Type

• Use VCS root credentials — TeamCity tries to extract username/password credentials or a personal access token/x-oauth-basic from the VCS root settings if the VCS root uses an HTTP(S) fetch URL. This option does 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 works.

• Access token — if you have a configured OAuth connection to GitHub, click the magic wand button to let TeamCity automatically retrieve the corresponding access token.

  

  Otherwise, if you insert a token manually issued on the GitHub side, make sure it has the following permissions or scopes:

  • Classic GitHub tokens: public_repo for public repositories, repo for private repositories. See also: Scopes for OAuth apps.

  • Fine-grained tokens: add the Pull requests permission with the "Read-only" access type. This permission can only be added for tokens with the "All repositories" or "Only select repositories" access type. See also: Permissions required for fine-grained personal access tokens.

• GitHub App access token — a non-personal short-lived token issued via the GitHub App. Available only when the VCS Root setting points to a specific VCS root configured using a GitHub App connection.

Discovery mode

Determines how TeamCity identifies pull requests:

• By branch specification refs (default) — TeamCity identifies pull requests by their actual refs/pull/N/head branches.

• By source branch names — Requests are identified by their source branches. Enabling mode has the following effects:

  • Pull requests from forks are ignored.

  • Different pull requests coming from the same source branch are aggregated into one, and can be processed inside the same build.

  • In TeamCity UI, source branch names are shown (compared to pull/N names in the default mode).

  • As a side effect, TeamCity more accurately synchronizes pull requests made to separate repositories if two configurations are linked into a build chain. For example, in the default mode, if an upstream configuration processes changes from the pull/10 branch, the downstream build runs against the same branch. Given that each repository has its own unique pull request counter, this chain can build unrelated changes. If the By source branch names mode is enabled, TeamCity recognizes that changes from the pull/10 branch of one repository correspond to the pull/54 branch of another one, since both originate from the same sandbox branch.

Note that switching this mode changes how TeamCity recognizes pull requests, which may cause an influx of new pull requests (and, if automatic triggers are configured, an influx of queued builds). This is a one-time spike in build volumes that resolves once all newly discovered pull requests have been processed.

By authors

Filters which pull requests TeamCity monitors by their author. Applies to public repositories only.

• Members of the same organization — only detects pull requests submitted by members of the same organization.

• Members and external collaborators — only detects pull requests submitted by members of the same organization and external collaborators.

• Everybody — detects all pull requests. Be aware that this option may allow arbitrary users to execute malicious code on your build agents.

By source branch

Restricts monitored pull requests to source branches matching this branch filter. Leave empty to apply no filter.

By target branch

Restricts monitored pull requests to target branches matching this branch filter. Leave empty to apply no filter.

Ignore Drafts

By default, the Pull Requests build feature loads GitHub draft pull requests information and runs builds on them — the build page shows a grayed-out icon and the Draft status next to the pull request number.

Check the box to ignore GitHub draft pull requests. TeamCity will not load draft pull request information until its status changes.

Server URL

A GitHub URL for connection. If left empty, the URL is 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:

Authentication Type

• Use VCS root credentials — TeamCity tries to extract username/password credentials from the VCS root settings if the VCS root uses an HTTP(S) fetch URL. This option does 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.

By source branch

Restricts monitored pull requests to source branches matching this branch filter. Leave empty to apply no filter.

By target branch

Restricts monitored pull requests to target branches matching this branch filter. Leave empty to apply no filter.

Server URL

A Bitbucket URL for connection. If left empty, the URL is extracted from the VCS root fetch URL.

Use pull request branches

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 source branches directly in a source repository (forks are not supported). If more than one pull request is submitted from the same source branch at the moment the build starts, TeamCity displays all these requests in the build results. However, only commits from open PRs matching the filtering criteria are 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:

Authentication Type

• Use VCS root credentials — TeamCity tries to extract username/password credentials from the VCS root settings if the VCS root uses an HTTP(S) fetch URL. This option does 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 for long-lived access to a repository, workspace, or project. The token must have the Pull Requests | Read scope.

By target branch

Restricts monitored pull requests to branches matching this branch filter. Leave empty to apply no filter.

GitLab Merge Requests

TeamCity processes GitLab merge requests similarly to how it processes pull requests in other hosting services. Currently, TeamCity only detects 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:

Authentication Type

• Use VCS root credentials — TeamCity tries to extract login credentials or an access token from the VCS root settings if the VCS root uses an HTTP(S) fetch URL. This option does not work if the VCS root employs anonymous authentication.

• Personal Access Token — use a personal access token issued in GitLab. It must have 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

Restricts monitored merge requests to source branches matching this branch filter. Leave empty to apply no filter.

By target branch

Restricts monitored merge requests to target branches matching this branch filter. Leave empty to apply no filter.

Ignore Drafts

By default, the Pull Requests build feature loads GitLab draft merge requests information and runs builds on them — the build page shows 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

A GitLab URL for connection. If left empty, the URL is extracted from the VCS root fetch URL.

Azure DevOps Pull Requests

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

For Azure DevOps, TeamCity detects requests on a merge branch — not on the pull request itself as with other VCSs. Each build is launched on a virtual branch showing the actual result of the build after merging the PR, so the build contains both the commit with changes and the virtual merge commit.

Note that the feature ignores Azure DevOps draft pull requests.

Authentication Type

• 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 the 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.

By source branch

Restricts monitored pull requests to source branches matching this branch filter. Leave empty to apply no filter.

By target branch

Restricts monitored pull requests to target branches matching this branch filter. Leave empty to apply no filter.

Project URL

A project URL for synchronization with the remote Azure DevOps server. Recommended for on-premises Azure DevOps installations. If left empty, the URL is 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 displays all these requests in the build results. However, only commits from open requests matching the filtering criteria are displayed as Changes of the build.

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

Connection

Choose a preconfigured connection to JetBrains Space.

By target branch

Restricts monitored merge requests to branches matching this branch filter. Leave empty to apply no filter.

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

1. Create a composite build configuration and attach your JetBrains Space VCS root with an empty branch specification to it.

2. Add the composite build configuration at the end of the build chain by configuring its snapshot dependencies on parallel builds with tests.

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

4. 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 automatically runs builds on changes in a merge request branch submitted to your JetBrains Space repo and publishes 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 requires 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.