Pull Requests

Common Information

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.

Interaction with VCS Roots

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

project {
    vcsRoot(SharedVcsRoot)
    buildType(PullRequestsConfig)
}

// VCS root with a branch spec
object SharedVcsRoot : GitVcsRoot({
    name = "shared-vcs-root"
    branch = "main"
    branchSpec = """
        refs/heads/main
        refs/heads/sandbox
        refs/heads/dev-*
    """.trimIndent()
})

// Build configuration that nullifies root's branch spec
object PullRequestsConfig : BuildType({
    name = "Pull Requests Config"

    vcs {
        root(SharedVcsRoot)

        branchFilter = """
            -:*
            +:refs/pull/*
        """.trimIndent()
        /* exclude all branches and re-add pull request ones */
    }
})

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.

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

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

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

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

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.

JetBrains Space Merge Requests

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.

Predefined build parameters for pull requests

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

Pull Requests workflow example

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:

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

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.

See also

Tutorials and Examples

TeamCity Blog

Pull Requests﻿

Common Information﻿

note

warning

Interaction with VCS Roots﻿

VCS-specific settings﻿

GitHub Pull Requests﻿

Bitbucket Server/Data Center Pull Requests﻿

Bitbucket Cloud Pull Requests﻿

GitLab Merge Requests﻿

Azure DevOps Pull Requests﻿

JetBrains Space Merge Requests﻿

tip

Predefined build parameters for pull requests﻿

Pull Requests workflow example﻿

Troubleshooting﻿