Teamscale Integration in Code Collaboration Suites (GitHub, GitLab, Gerrit, etc.)
Dr. Alexander von Rhein
Many software development projects use online tools for collaboration between developers. For example, developers use GitLab, GitHub, Jira, and Gerrit for asynchronous discussions about code, for reviewing features before accepting them into the »main« branch, and for executing automated tests.
Usually, the impact of a feature on code maintainablility is not easily visible in such tools (it is hard to judge this from a simple code diff). Some newly introduced maintainability flaws such as new architecture violations or code that is cloned from non-changed existing code are impossible to recognize when seeing only the changed code. Even if a Teamscale instance exists that contains findings on code quality, opening it is an effort that is often skipped by reviewers.
In this blog post, I illustrate how Teamscale results can be integrated easily in existing online-collaboration tools. This helps to make existing code-review processes more thorough and efficient.
Teamscale Integration in Development Collaboration Suites
As more and more software development teams integrate development-collaboration suites such as GitLab, GitHub, Jira or Gerrit into their workflow, Teamscale also has integrations into these suites.
Some years ago most development teams used plain version-control servers (e.g., SVN or Git), often without a graphical user interface. Collaboration and synchronization between the developers happened via branching, special marker comments in the code, or offline discussions. Now, many development teams use rich collaboration suites which offer facilities for asynchronous communication such as reviews, task assignment, and discussions about code.
Teamscale always provided means for individual access to its findings and metrics. It integrates into development IDEs such as Eclipse, IntelliJ, and Visual Studio and is accessible via web browsers. However, we developed integration in collaborative suites only recently. I will highlight some ways to propagate Teamscale’s information (metrics, findings) into collaborative development suites and how this makes development workflows more efficient.
The main Teamscale-related question that occurs when working with development suites is »What would happen to the main branch when I merge/accept this new feature?« The development suites are very good at answering this question with respect to the code changes (they show a code-diff view) and test failures (they show CI test results). However the impact on maintainability is usually not directly visible. Our integrations solve this problem by showing how the findings and metrics of the main branch would change when a feature-branch would be merged.
We developed special apps/plugins for some suites (GitHub and Gerrit) and a implemented an SVG-generation service in Teamscale that can be used to integrate Teamscale into any other tool that can load images from user-defined URLs (e.g., GitLab and Jira). I will illustrate each of these integrations below.
Teamscale's GitHub Integration
We built a GitHub app that connects your project in GitHub to your Teamscale instance. The GitHub app must be installed and configured by the GitHub administrator (see details in Teamscale's documentation). Then it shows for each pull request how many findings would be merged.
In this example, accepting the pull request would introduce one additional finding on the master branch. The reviewer of this pull request can investigate the finding by clicking on »Details«. Then the reviewer can decide either to accept this additional finding, or that the finding should be resolved before merging the pull request.
Teamscale's Gerrit Integration
The Gerrit integration is implemented as a plugin to the Gerrit review tool. It supports the reviewer by annotating each line that receives a new finding.
In the example, there is a TODO left in the code and Teamscale is configured to generate a finding for each TODO comment. In this situation, the reviewer has to decide whether having the TODO on the main branch is acceptable.
Gitlab and other tools: SVG-based integration
In addition to the integration plugins tailored to specific development suites, we offer a set of generic services that can be used to integrate Teamscale into many suites.
I illustrate this using our own GitLab instance and our own Teamscale server as an example. The following screenshot is from a merge request in our Teamscale development project.
The screen shot contains two badges (marked with the legend boxes). Both badges are SVG images that are generated by our Teamscale instance when the merge-request page is loaded.
The left badge shows the predicted finding churn that would occur on the master branch if this merge request would be merged now. We would add 2 new findings and remove 31 findings that are on the current master branch. In addition, there are 2 unresolved findings in code that has been changed in this merge request (maybe the author of this merge request has enough context information to resolve these old findings, even though he did not introduce them).
The right badge shows the test-gap assessment of this merge request. That is the percentage of methods changed or added in this merge request that have not been executed in tests. For a more detailed discussion of Test Gaps, see the Article »Take control of your testing process!« of my colleague Fabian Streitel.
The information given by these two badges supports the reviewer in deciding whether he can accept the changes. When the badges show new findings or a test gap, the reviewer can quickly investigate these via the Teamscale User Interface. In our experience, opening Teamscale to search for added findings is often skipped during reviews because it takes too long. Therefore, the badges improve the effectiveness of the reviewer (potentially more errors found) and his efficiency (no need to open Teamscale for merges without findings/test gaps).
The badges are integrated into the merge-request description field via GitLab’s markup language. Each badge is integrated as an image loaded from a URL linking to a Teamscale service. For example, the finding badge is integrated as this HTML tag:
This badge service allows integration into any tool that can load SVG images from dynamic URLs (the url must contain the source and target branches). In our case, a GitLab Merge-Request hook inserts the HTML tags when a merge request is created or the target branch of a merge request changes. Please contact us for more information on how to integrate Teamscale information into your development process. https://www.cqse.eu/en/support/