Pull Request Decoration
Starting from version
7.8.0, sonar-scala can be run in a decoration mode,
which can analyse GitHub pull requests and make comments on any new issues
directly on the pull request. Version
8.4.0 and later support
This functionality is similar to what was provided by the GitHub Plugin, which was deprecated in SonarQube 7.2 and replaced by similar functionality in the paid Developer Edition. SonarCloud also offers PR decoration, but it requires a paid subscription for private projects.
See some examples below:
sonar-scala also reports a status check at the end of the analysis - passed if no critical or blocker issues are found, or failed otherwise.
- Create a new dedicated Github account (you can use your existing bot/CI account if you already have one).
- Generate a new personal access token for your account. The token can be
generated in the developer settings on
Github. Select the
public_reposcope for public repositories or
repofor private repositories (or a mix of public and private repositories).
- Make sure you give your user write permissions to the repositories you want to decorate your PRs for, otherwise sonar-scala will fail as it won't be able to set a status of the PR check.
Before you execute PR decoration, you need to check out the latest commit of the branch which was used to open the pull request. Once you've done that, you can run sonar-scala in decoration mode by setting the following properties:
- sonar.scala.pullrequest.provider - currently, only
- sonar.scala.pullrequest.number - number of the pull request; if you use
CircleCI, you can use the
CIRCLE_PR_NUMBERenv variable, Travis has
- sonar.scala.pullrequest.github.repository - name of the repository
including organisation name in the following format
- sonar.scala.pullrequest.github.oauth - Github personal access token that you generated in the previous step
sonar.scala.pullrequest.github.apiurl - specify GitHub API url for GitHub Enterprise, e.g.
https://github.mycompany.com/api/v3. This property defaults to the public GitHub API -
sonar.scala.pullrequest.dryrun - execute PR decoration in "dry run" mode (sonar-scala will not post the results to Github). This setting is useful for testing purposes in combination with
sonar.verbose=true. You usually won't need to use this setting, unless you run into any issues.
Once you run sonar-scala in decoration mode, instead of sending the results to SonarQube it will post the relevant comments to Github, which results in creating an empty project in SonarQube. This is necessary to make this feature work since the Community Edition of SonarQube doesn't have the support for branch analysis. sonar-scala works around that limitation by having an empty project so that it can still be executed, analyse your code and post any comments back to Github.
You can create an empty project yourself, or you can let sonar-scala do this for you. If your SonarQube instance requires authentication to execute an analysis, you need to make sure that your user has the right permissions to create a new project and execute an analysis, or just the permission to execute analysis if you created a new project yourself. Once you created a new blank project, you can use it across all of your projects.
The following example shows how to run sonar-scala in decoration mode for pull request 1 in the mwz/sonar-scala-pr-annotation-example repository on Github. Notice the project name and key are set to match the dedicated blank project in SonarQube, which isn't the same project you would normally use to execute an analysis in a "normal" mode.
-Dsonar.projectName='PR Decoration' \
If you want to have this automated by your CI, which is ideally how it's
intended to be used, the pull request setting will be different for each pull
request. Most of the modern CI tools allow you to use a built-in environment
variable to get the current pull request number - as mentioned previously,
CIRCLE_PR_NUMBER and Travis provides