Integrate CodeScene in your CI/CD Pipeline

By integration CodeScene into your CI/CD Pipeline and/or your Pull and Merge Requests, you get the following advantages:

  • Quality gates for hotspot goals.

  • Quality gates for Code Health decline.

  • Automated code review of new modules.

  • Early warnings such a complexity trend increase or detect the absence of expected change coupling.

  • Prioritize code reviews based on the risk of the commits.

The integration is automated for GitHub, BitBucket, BitBucket Server, GitLab, Azure DevOps, and Gerrit.

CodeScene also provides an official Jenkins plugin + a CircleCI orb + a REST API and library for integrations with any other platform or build pipeline (custom integrations are described in CI/CD Integration with CodeScene’s Delta Analysis).

To enable the pull request (PR) integration, you go to the project configuration and select your Git provider:

Enable the automated pull request integration to use CodeScene as review input and quality gate.

Fig. 29 Enable the automated pull request integration to use CodeScene as review input and quality gate.

All that is required are API credentials (API Token/App Password) authorized to modify webhooks and pull requests. Enter the proper credentials, and press “Save Configuration”. CodeScene will now act on new or modified PRs and provide an automated review:

CodeScene provides automated pull request reviews.

Fig. 30 CodeScene provides automated pull request reviews.

Use Cases and how to interpret the results

The use cases and configuration options are explained in CI/CD Integration with CodeScene’s Delta Analysis.

Control the pull request comments

By default, CodeScene will only post a PR review comment if a) a quality gate fails, or b) the change is high risk and has a higher recommended review level. You can change this defaults inside your project’s configuration:

Configure how often you want CodeScene to comment on your PRs.

Fig. 31 Configure how often you want CodeScene to comment on your PRs.

Note that Delta Analysis will only be performed if the CodeScene project is configured to analyse the PR target branch. To analyse PRs with different target branches, you need to set up one CodeScene project per target branch.

Pull Requests: Statistics, Actions, and Impact

No matter what baseline we start from, we never want our code to become harder to read, understand, or maintain. CodeScene’s pull request integration lets you stay on top of your development so that you can prioritize and act upon any negative trends. For that purpose, CodeScene visualizes the impact of pull requests over time:

View the impact and developer action due to the pull request integration.

Fig. 32 View the impact and developer action due to the pull request integration.

The presented statistics are:

  • Checks performed: This is the total number of pull request analyses run by CodeScene.

  • Detected Violations: A violation is either a violated goal (e.g. a planned refactoring never happened), a reported code health decline, or new code with code health issues.

  • Positive Actions: A positive action is when one of the detected violations is acted upon and mitigated.

  • Violations Ignored: This is the number of detected violations that were merged as-is, without remediation, to the main branch. Ignored violations lead to a failed goal and/or a code health decline.

CodeScene also calculates the total code health impact and presents it as monthly trends. These trends let you visualize and communicate improvements, as well as taking actions upon a larger decline:

View the code health impact of the pull request integration.

Fig. 33 View the code health impact of the pull request integration.

In the preceding example, we see that Codebase A took on a significant amount of technical debt during November. This code health decline would also be reported as alerts on the CodeScene dashboard when the pull requests are merged. A recommended action in this case would be to plan goals to manage the new debt (see Manage Hotspots and Technical Debt with Goals).

Contrast this with Codebase B which shows a positive trend where smaller code improvements are delivered continuously.

Finally, you can inspect the details of individual pull requests if you need to drill down even further:

CodeScene presents detailed statistics per pull request, allowing a deeper drill down.

Fig. 34 CodeScene presents detailed statistics per pull request, allowing a deeper drill down.

You can find the pull request statistics on your project’s analysis dashboard:

The dashboard includes pull request statistics and a link to view more details.

Fig. 35 The dashboard includes pull request statistics and a link to view more details.

Supported Integrations

CodeScene Jenkins Plugin

CodeScene provides an official Jenkins plugin, available via Jenkins Update Center.

More detailed installation and configuration instructions are available here.

Integrate CodeScene with GitHub Checks API

Codescene can integrate with GitHub to provide quality gates for Pull Requests on the Checks tab. To do this, you must create a GitHub App and use the settings for that app when configuring CodeScene.

CodeScene acts as a GitHub Check.

Fig. 36 CodeScene acts as a GitHub Check.

Follow these steps to enable the Check:

1. Creating a GitHub App

Follow Steps 1–5 here to start creating your GitHub App. Then do the following settings.

  • Homepage URL. The Homepage URL setting is required by GitHub, but you can set it to anything (such as https://www.codescene.io/).

  • Webhook. Set to not active. You will activate it after doing settings in CodeScene.

  • Repository Permissions Grant the following permissions:

Permission

Access

Checks

Read & write

Pull Requests

Read-only

  • Click Create GitHub App. This will take you to your new GitHub App’s page.

  • Private Key. Scroll down to the bottom of the page and click Generate Private Key. This will download a .pem file.

  • Click Save changes.

2. Configure CodeScene’s PR integration

Go to the PR integration tab in the CodeScene project configuration and do the following settings:

  • Select GitHub App.

  • App ID. Copy the value from your GitHub App and set it here.

  • Private Key. Select the .pem file you downloaded when creating the App.

  • Webhook Secret. Specify a value that will be used for encrypting webhook calls.

  • Save the CodeScene GitHub App configuration.

3. Configure the webhooks on your GitHub App

Go to the configuration page for your GitHub App and do the following settings:

  • Webhook. Set to active

  • Webhook URL. Copy the value from the CodeScene GitHub App configration and set it here.

  • Webhook Secret. Set the same value as in your CodeScene Github App configuration.

  • Subscribe to events. Go to the Permissions & Events tab and add subscriptions to Check run, Check suite and Pull request events.

  • Click Save Changes

Install your GitHub App from the settings page for the app. Codescene will now receive webhook calls when PRs are created or updated on any repositories where you have installed the App. If any Quality Gate is triggered, CodeScene will fail the check and present the results on the Check Run details page:

GitHub Check Run details

Fig. 37 Example of Check Run details in GitHub

GitHub annotations

CodeScene can also create annotations for all Code Health changes in a Pull Request. The annotations will be visible on the Check Run details page:

GitHub annotations in Check Run details

Fig. 38 Example of annotations in GitHub Check Run details

The annotations will link directly to code being modified in the Pull Request, and will also be visible when reviewing the modified files:

GitHub annotations in file view

Fig. 39 Example of annotations in GitHub file view

Annotations will be produced for improvements as well as for degradations. If the Code Health score for the specific biomarker is not degrading, the annotations will be created as notices rather than warnings.

You can enable the annotations by checking an option in the Pull Request integration settings:

Enable GitHub annotations

Fig. 40 Enable GitHub annotations

Integrate CodeScene in build pipelines using codescene-ci-cd

We provide an open source library that encapsulates the CodeScene integration. Using this library, you can easily add delta analysis steps to build pipelines. See the library documentation for configuration examples and options: codescene-ci-cd.

CodeScene Orb for CircleCI Integration

CodeScene provides an official CircleCI Orb, available directly via the CircleCI Orb Registry.

CodeScene Integration with Gerrit

You can integrate with Gerrit using the following options:

  1. Webhooks: Enable the webhooks for Gerrit in your CodeScene project configuration. This adds automated review comments to Gerrit’s patch sets.

  2. Build Bot: Use CodeScene’s Jenkins plugin as a code review bot (+1).

One important note on the Gerrit integration: Gerrit provides a staging area for code to be reviewed. This staging area is kept separate from the main, authorative Git repository. As a consequence, the commits for a delta analysis aren’t available in the main Git repository, but in Gerrit’s mirror of the repository.

CodeScene lets you resolve this by specifying a different origin_url and a specific change_ref to fetch before the delta analysis is run. Here’s an example:

curl -X POST -d '{"commits": ["149f9e6"], "repository": "PhpSpreadsheet", "origin_url": "gerrit.mycompany.com:39429/dev/wopr", "change_ref": "refs/changes/82/577659/7"}' http://localhost:3003/projects/64/delta-analysis -u 'CodeReview:MyPassword' -H "content-type: application/json"

That is, CodeScene will fetch a specific change set from Gerrit and then run the delta analysis as indicated by the other parameters you provide.

CodeScene integration with GitLab

Enable the webhooks for GitLab in your CodeScene project configuration. This adds automated Merge Request comments to GitLab.

Results are presented as Discussion comment in the Merge Request:

GitLab MR Comment

Fig. 41 A successful check

If PR check is successful then the comment is resolved, otherwise it’s unresolved. Status is shown with a green checkmark (red arrow points to it).

This is useful if you set the restriction to prevent merge if there are unresolved comments.

Instead of posting one comment, CodeScene can add discussions to specific lines of files where code degradations and improvements occurred.

GitLab MR Discussion in changed file

Fig. 42 A discussion in files view

CodeScene integration with Bitbucket Cloud

Analysis results will be presented in a Pull Request comment. You can also choose to add Code Insights Report and/or a Build status, all options being enabled by default.

In Bitbucket Build Status can be made a requirement for merging the Pull Request, acting as a Quality Gate. Alternatively you can get a Code Insights Report, which will not prevent merges if you have configured successful builds to be a requirement.

Bitbucket PR comment

Fig. 43 Example of a Pull Request comment in Bitbucket

Bitbucket PR report

Fig. 44 Code Insights Report is located bottom of the right sidebar of Bitbucket PR

If Code Insights Report is enabled, CodeScene can add annotations to specific lines of files where code degradations and improvements occurred.

Bitbucket PR report file annotations

Fig. 45 Code Insights Report with file annotations

Bitbucket PR report

Fig. 46 Build Check in the right is located in the middle of the right sidebar of Bitbucket PR

CodeScene integration with Azure DevOps

Azure result presentation

Results are presented as status check and a PR comment.

Azure Status Check

Fig. 47 A failed Status Check

You can make the check mandatory for merging into a specific branch:

  • go to Azure’s Project Settings

  • Repositories

  • select a repository

  • Policies tab

  • select “master” or similar main branch in Branch Policies

  • Status Checks, click + button to add one

On this same page you can also enable: Check for comment resolution. Since CodeScene’s PR comments on failed checks are Unresolved, this setting forms a Quality Gate that prevents PR merging, unless PR comment is manually marked as resolved. This gives a nice flexibility where CodeScene’s failed PR check can be manually overridden.

Instead of posting one comment, CodeScene can add discussions to specific lines of files where code degradations and improvements occurred.

Azure PR Thread in changed file

Fig. 48 A thread in files view