Lessons Learned: Bitbucket PR Build Integration with TeamCity
One of the most important steps that needs to be considered for having faster development, less painful times, and faster time to market is to have a stable master branch. In order to have a stable master branch, it is important to always detect problems as early as possible. Detecting problems as early as possible has so many ways and techniques, one of the most important ways is to make sure that every incoming pull request (a.k.a PR) to the project is always validated before it is getting merged to master branch. This article discusses the steps which should be taken into consideration to successfully perform this sort of PR build/unit tests integration between git server and CI server (taking Bitbucket Server and TeamCity as an example).
Why this integration is needed
Making sure that every incoming pull request is validated before it is getting merged will allow us to avoid facing surprises later when PRs are getting merged to master. Validating a PR means mainly achieving the following minimum steps:
- PR is built correctly without any compilation errors or any other types of static analysis validation errors such as check style problems.
- Unit tests pass successfully.
- Basic Integration tests pass successfully.
These minimum steps can be extended (or customized) by every project based on its structure and requirements.
Working Flow
The idea behind this integration is simply to have the CI server automatically builds and runs unit tests for every newly created PR (and for every change to any opened PR), and then notify git server if build goes successful or not. This should happen seamlessly with every new PR without having to perform any manual steps from the developers’ side.
Again, for the scope of this article, I would like to show an integration case between Bitbucket server and Team City for PR build and unit tests validation. I would also assume that the current used flow for the project is Git workflow.
The following diagram explains the interaction flow in detail for all participants in the PR flow.
Now, enough theory, let’s go into the steps that are required to perform this integration between Team City and Bitbucket server.
Install and Configure “Commit Status Publisher” plugin
Currently, there are two available add-ons for TeamCity that can be used for integration with Bitbucket server. The first one is developed by JetBrains and it is called “Commit Status Publisher”. The other one is called “TeamCity Stash Integration” plugin which is developed by Mendhak.
I will focus on “Commit Status Publisher” plugin since this is the one that I tried and works perfect with me.
“Commit Status Publisher” plugin is compatible with TeamCity 7.1.x and later and is bundled since TeamCity 10.x.
Assuming that you have the plugin in place, let’s configure the plugin to communicate commit status back to Bitbucket server.
In your build configuration, add a build feature and specify the following parameters:
- Use the
“All attached VCS roots”as a VCS root. - Select
“Bitbucket Server”as the publisher. - Specify its connection details and credentials
- Save your settings.
Configure VCS Trigger
In the per-checking Triggering, make sure to check “Trigger a build on each check-in” as shown below.
Monitor All Refs!
Unfortunately, due to a limitation in Bitbucket server, you cannot just build pull requests to get their build statuses. Unlike GitHub, the following PR refs pattern +:refs/pull-requests/*/merge will not work with Bitbucket server.
The only solution that works with Bitbucket server is to build literally everything regardless of the branch, you can do this by simply specify +:refs/heads/* in the VCS Root branch specification as shown below.
There were some community discussions about this limitation/solution as well here https://github.com/mendhak/teamcity-stash/issues/22
If anyone has a better solution for this, feel free to comment, thanks
After performing these steps, we can finally see the status updates with every PR we create or change as shown below.
Conclusion
Integrating build and unit tests with every PR is essential for detecting problems as early as possible and having faster development and less painful time. This article showed a use case and the detailed steps required to configure Bitbucket server with Team City.
