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 of the following VCS (Version Control Systems) hosting services:
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 and triggers builds only on head
branches (such as refs/pull/*/head
).
After a build is run on a pull request, TeamCity provides additional details for the pull request branch on the Build Overview page.
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/ This option will not work if the VCS root employs anonymous authentication or SSH. For a GitHub Enterprise repository, only the personal access token/ |
Access token | The 'Token' field appears. Use a personal access token or obtain a token through an OAuth connection. It must have either the | |
By authors | 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 | Specify the name of the target branch. 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 | Specify the name of the target branch. 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 |
By target branch | Specify the name of the target branch. 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. |
Pull Requests workflow example
Let's say you have the following environment set up:
public GitHub repository
web-app
with the default branchmaster
- TeamCity project
build configuration
web-app
that uses files from theweb-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:
- 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.
- 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, when a member of your GitHub organization sends a pull request to the master
branch, TeamCity acts as follows:
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 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
See also:
TeamCity Blog: Building GitHub pull requests with TeamCity