SonarCloud extension for Azure DevOps

The SonarCloud extension for Azure DevOps makes it easy to integrate analysis into your build pipeline. The extension allows the analysis of all languages supported by SonarCloud.

The extension embeds its own version of the SonarScanner for .NET.

Installation

1. Install the extension from the Microsoft marketplace. If you are using Microsoft-hosted build agents then there is nothing else to install. The extension will work with all of the hosted agents (Windows, Linux, and macOS).
2. If you are self-hosting the build agents, check that at least the minimal version of Java supported by SonarCloud is installed. In addition, make sure the appropriate build tools are installed on the agent for the type of project you are analyzing. For example, .NET Framework v4.6.2+/NET Core 3.1+ if building using MSBuild, Maven for Java projects, etc.

Configuration

First of all, you have to declare SonarCloud as a service endpoint in your Azure DevOps project settings.

1. Open the Connections page in your Azure DevOps project: Project Settings > Pipelines > Service Connections.
2. Select New service connection and choose SonarCloud.

Each extension provides three tasks you will use in your build pipeline to analyze your projects:

• Prepare Analysis Configuration task: To configure all the required settings before executing the build.
  • This task is mandatory.
  • In the case of .NET solutions or Java projects, it helps to integrate seamlessly with MSBuild, Maven, and Gradle tasks.
• Run Code Analysis task: To execute the analysis of the source code.
  • This task is not required for Maven or Gradle projects because the scanner will be run as part of the Maven/Gradle build.
  • You can specify which version of Java to use for analysis. The options are:
    • JAVA_HOME:  The scanner picks up the current value of the JAVA_HOME environment variable on the system, so you are free to choose the value. The specified version must be supported by SonarCloud.
    • JAVA_HOME_11_X64: When you run your pipeline on a self-hosted build agent, this variable is normally set, and the scanner picks it up automatically. If no variable is detected, the scanner uses the value of JAVA_HOME.
    • JAVA_HOME_17_X64: When you run your pipeline on a self-hosted build agent, this variable is normally set, and the scanner picks it up automatically. If no variable is detected, the scanner uses the value of JAVA_HOME.
• Publish Quality Gate Result task: To display the quality gate status in the build summary and give you a sense of whether the application is ready for production "quality-wise".
  • This task is required if you are using the SonarCloud Quality Gate status pre-deployment gate in a release pipeline; otherwise, it is optional.
  • This task can significantly increase the overall build time because it will poll SonarCloud until the analysis is complete. Omitting this task will not affect the analysis results on SonarCloud. It simply means the Azure DevOps Build Summary page will not show the status of the analysis or a link to the project dashboard on SonarCloud.

When creating a build pipeline you can filter the list of available tasks by typing "Sonar" to display only the relevant tasks.

Analyzing a .NET solution

1. In your build definition:
   • Add at least the Prepare Analysis Configuration task and the Run Code Analysis task.
   • Optionally add the Publish Quality Gate Result task.
2. Reorder the tasks to respect the following order:
   • Prepare analysis on SonarCloud task: Place before any MSBuild or Visual Studio Build tasks.
   • Run Code Analysis task: Place after the Visual Studio Test task.
   • Publish Quality Gate Result task: Place after the Run Code Analysis task.
3. Click on the Prepare analysis on SonarCloud build step to configure it:
   • You must specify the service connection (for example, SonarCloud) to use. You can then:
     • Select an existing endpoint from the drop-down list.
     • Add a new endpoint.
     • Manage existing endpoints.
     • Specify which SonarCloud Organization to use by choosing an organization from the drop-down.
   • Keep Integrate with MSBuild checked and specify at least the project key.
     • Project Key: The unique project key in SonarCloud.
     • Project Name: The name of the project in SonarCloud.
     • Project Version: The version of the project in SonarCloud.
4. Click the Visual Studio Test task and select the Code Coverage Enabled checkbox to process the code coverage and have it imported into SonarCloud. See Test Coverage for more information.

Once you have done all of this, you can trigger a build.

Analyzing a Java project with Maven or Gradle

1. In your build definition:
   • Add at least Prepare Analysis Configuration task.
   • Optionally add the Publish Quality Gate Result task (required if you want to check the quality gate in a release pipeline).
2. Reorder the tasks to respect the following order:
   • Prepare analysis on SonarCloud task: Place before the Maven or Gradle task.
   • Publish Quality Gate Result task: Place after the Maven or Gradle task.
3. Click on the Prepare analysis on SonarCloud task to configure it:
   • Select the SonarCloud Service Endpoint.
   • Select your SonarCloud organization.
   • Select Integrate with Maven or Gradle.
4. On the Maven or Gradle task, in Code Analysis, check Run SonarQube or SonarCloud Analysis.

Once all this is done, you can trigger a build.

Analyzing a C++ project

In your build pipeline, insert the following steps in the order they appear here. These steps can be interleaved with other steps of your build as long as the following order is followed. All steps have to be executed on the same agent.

1) Make Build Wrapper available on the build agent: Download and unzip Build Wrapper on the build agent (see Prerequisites section of C/C++/Objective-C page). The archive to download and decompress depends on the platform of the host. Note that:

• For the Microsoft-hosted build agent, you will need to do it every time (as part of the build pipeline) but you can add a PowerShell script task to make this process easier. This can be done by inserting a Command Line task. 
• Example of PowerShell commands can be found on a Windows host: 

Invoke-WebRequest -Uri 'https://sonarcloud.io/static/cpp/build-wrapper-win-x86.zip' -OutFile 'build-wrapper.zip'
Expand-Archive -Path 'build-wrapper.zip' -DestinationPath '.'

• Example of bash commands on a Linux host:

curl 'https://sonarcloud.io/static/cpp/build-wrapper-linux-x86.zip' --output build-wrapper.zip
unzip build-wrapper.zip

• Example of bash commands on a macOS host: 

curl 'https://sonarcloud.io/static/cpp/build-wrapper-macosx-x86.zip' --output build-wrapper.zip
unzip build-wrapper.zip

• For the self-hosted build agent, you can either download it every time using the same scripts or use it just once, as part of the manual setup of the build agent.

2) Add a Prepare Analysis Configuration task and select the Prepare Analysis on SonarCloud task to configure it:

• Select the SonarCloud Service Endpoint.
• Select your SonarCloud organization
• In Choose the way to run the analysis, select standalone scanner (even if you build with Visual Studio/MSBuild)
• In Additional Properties in the Advanced section, add the property sonar.cfamily.build-wrapper-output with, as its value, the output directory to which the build wrapper should write its results.

3) Add a Command Line task to run your build. For the analysis to happen, your build has to be run through a command line so that it can be wrapped up by the build-wrapper:

• Run the build wrapper executable. Pass in as the arguments 1) the output directory configured in the previous task and 2) the command that runs a clean build of your project (not an incremental build). Example of PowerShell commands on a Windows host with a MSBuild build: 

build-wrapper-win-x86/build-wrapper-win-x86-64.exe --out-dir <output directory> MSBuild.exe /t:Rebuild

• Example of bash commands on a Linux host with a make build: 

build-wrapper-linux-x86/build-wrapper-linux-x86-64 --out-dir <output directory> make clean all

•  Example of bash commands on a macOS host with an xcodebuild build: 

build-wrapper-macosx-x86/build-wrapper-macos-x86 --out-dir <output directory> xcodebuild -project myproject.xcodeproj -configuration Release clean build

4) Add a Run Code Analysis task to run the code analysis and make the results available to SonarCloud. Consider running this task right after the previous one as the build environment should not be significantly altered before running the analysis.

5) Optionally, add a Publish Quality Gate Result task (required if you want to check the quality gate in a release pipeline).

Once all this is done, you can trigger a build.

Analyzing other project types

If you are not developing a .NET application or a Java project, here is the standard way to trigger an analysis:

1) In your build definition, add:

• At least Prepare Analysis Configuration task and Run Code Analysis task.
• Optionally Publish Quality Gate Result task (required if you want to check the quality gate in a release pipeline).

2) Reorder the tasks to respect the following order:

1. Prepare analysis on SonarCloud
2. Run Code Analysis
3. Publish Quality Gate Result

3) Click on the Prepare analysis on SonarCloud task to configure it:

• Select the SonarCloud Service Endpoint.
• Select your SonarCloud organization.
• Select Use standalone scanner.
• Then:
  • Either the Sonar properties are stored in the (standard) sonar-project.properties file in your SCM, and you just have to make sure that "Settings File" correctly points at it. This is the recommended way.
  • Or you don't have such a file in your SCM, and you can click on Manually provide configuration to specify it within your build definition. This is not recommended because it's less portable.

Once all this is done, you can trigger a build. 

Branch and pull request analysis

Branch analysis

When a build is run on a branch of your project, the extension automatically configures the analysis to be pushed to the relevant project branch in SonarCloud. The same build definition can apply to all your branches, whatever type of git repository you are analyzing.

If you are working with branches on TFVC projects, you still need to manually specify the branch to be used on SonarCloud: In the Prepare Analysis Configuration task, in the Additional Properties, you need to set sonar.branch.name.

Pull request analysis

SonarCloud can analyze the code of the new features and annotate your pull requests in Azure DevOps with comments to highlight issues that were found.

Pull request analysis is supported for any type of git repository. You have two possibilities to activate it, depending on where your code is hosted. If your code is on Azure DevOps, use branch policies. If your code is on GitHub or Bitbucket Cloud, use a pull request validation trigger.

Using branch policies on Azure DevOps

The Microsoft documentation on setting up build validation for Azure Git is here. There are three basic steps to set this up in SonarCloud:

1. In the Branch policies page of your main development branch, add a build policy that runs your build pipeline.
2. Create an Azure DevOps Personal Access Token having a Code (read and write) scope.
3. In SonarCloud, set this token by navigating to Your Project > Administration > General Settings > Pull Requests > Integration with Azure DevOps Services.

Next time some code is pushed in the branch of a pull request, the build pipeline will execute a scan on the code and publish the results in SonarCloud which will in turn, decorate the pull request in Azure DevOps.

Please note that this feature will prevent you from merging into the target branch until the quality gate is green.

After the first analysis on a pull request, you can also activate the Require approval from additional services feature (note that you will not see the SonarCloud quality gate in the following dropdown until the analysis build has been run once) :

1. Go to the Branch policies page of your main development branch.
2. Under Require approval from additional services, select Add status policy.
3. In the Status to check dropdown, select SonarCloud/quality gate.
4. Then choose either Required or Optional depending on your need, and click on Save.

This feature will check the quality gate status for each pull request. Users will not be able to merge a pull request until the check has been completed. If you made the check Optional, users will be able to merge a pull request even if the quality gate is red. If you made the check Required, users will not be able to merge a pull request unless the quality gate is green.

Using a pull request validation trigger on GitHub or Bitbucket Cloud

If you want to activate the pull request analysis for GitHub or Bitbucket Cloud:

1. Select Edit to modify your build pipeline.
2. Go to the Triggers tab.
3. Select the correct repository under Pull request validation.
4. Select Enable pull request validation.
5. Set up the branch filters: Note that this is the target branch of the pull request. See the Microsoft documentation for more details.
6. Select Save to update your pipeline.

Using release pipelines

You can check the SonarCloud quality gate status in your release pipeline. It takes place as a pre-deployment gate.

1. In the release pipeline, add a stage, then click on pre-deployment conditions.
2. Enable the gates, then click on add. Choose SonarCloud Quality Gate status check.
3. Save your pipeline.

This feature is currently in preview, and the following notes are important :

• The Publish Quality Gate Result task in your build pipeline has to be enabled to get this gate working.
• If the quality gate is in the failed state, it will not be possible to get the pre-deployment gate passing as this status will remain in its initial state. You will have to execute another build with either the current issues corrected in SonarCloud or with another commit for fixing them.
• The pre-deployment gates in the release pipeline check the status every five minutes for one day, by default. If you know that the SonarCloud quality gate has failed and will remain in the failed state on Azure DevOps, you can increase this duration to a maximum of 6 minutes (so the gate will be evaluated only twice), or just cancel the release itself.
• Only the quality gate related to the primary build artifact of the release will be checked.
• During a build, if multiple analyses are performed, all of the related quality gates are checked. If one of them has the status WARN, ERROR, or NONE, then the quality gate status on the release pipeline will be failed.

Quality gate status widget

You can monitor the quality gate status of your projects directly in your Azure DevOps dashboard. Follow these steps to configure your widget:

1. Once the Azure DevOps extension is installed and your project has been successfully analyzed, go to one of your Azure DevOps dashboards (or create a new dashboard). Click on the Pen icon to edit, and then select Add Widget.
2. In the Add Widget list, select Code Quality, and then click Add. An empty Configure widget is added to your dashboard.
3. Next, click on the widget's Cogwheel icon to configure it.
   • For public projects, you can simply select your project from the dropdown. A search bar inside the drop-down will help you find it easily. Just select it and click Save.
   • For private projects, log in using the links provided under the drop-down. Once logged in, your private projects will appear in the drop-down. Select the project you are interested in, and click Save.

Using the Prepare Analysis Configuration task

The Prepare Analysis Configuration task will configure all the required settings before executing the build. This task is mandatory. In the case of .NET solutions or Java projects, this task helps to integrate seamlessly with MSBuild, Maven, and Gradle tasks.

Entries you make into the Prepare Analysis Configuration task will be formatted by the SonarCloud extension as the SonarCloudPrepare settings task in your azure-pipelines.yml file. When editing your pipeline in Azure DevOps, clicking on Settings is a good way to edit the task because the extension will automatically populate the relevant properties. In this image, you can see how, for example, the projectKey you entered in the Prepare Analysis Configuration task is automatically formatted in the SonarCloudPrepare settings task.

SonarCloudPrepare task properties

These properties can be defined, should they be useful to your workflow:

Required properties

• cliSources
  • Note: Path to the root directory containing source files. This value is set to the sonar.sources SonarCloud property.
  • Default: .
• configMode
  • Note: This property is required, but only needs to be modified if you specify the optional configFile property. Choose one of the options as your preferred configuration method. 
  • Options: 
    • file: Store configuration with my source code in sonar-project.properties
    • manual: Manually provide configuration mode
  • Default: file
• projectKey or cliProjectKey
  • Note: The project’s unique key. Allowed characters are letters, numbers, -, _, ., and :, with at least one non-digit.
  • Default: <yoursonarcloudusername_yourprojectname>
• scannerMode
  • Note: scannerMode should be defined using the Prepare Analysis Configuration task, part of the SonarCloud extension for Azure Pipelines. Go to the UI of your Azure DevOps project pipeline to choose the way to run the analysis.
• SonarCloud Server Endpoint
  • Note: Is usually defined in the Azure > Project settings > Service connections and is not possible to define manually. Requires a token generated during the SonarCloud Analyze new project setup.
  • Default: The name of the Service connection you created in Azure DevOps.

Optional properties

• configFile
  • Note: The path to the file containing your SonarCloud configuration. 
  • Default: sonar-project.properties
• extraProperties
  • Note: Additional properties to be passed to the scanner. Specify each key=value pair on a new line. See the Analysis Parameters and Analysis Scope pages for more detail on optional parameters. 
  • Note: Put one key=value per line; for example: sonar.exclusions=**/*.bin
• projectName or cliProjectName
  • Note: The name of the project that will be displayed on the web interface. The cli prefix shall be used only while running in cli scanner mode.
  • Default: For Maven projects: <name>; otherwise the projectKey. 
• projectVersion or cliProjectVersion
  • Note: The project version. Do not use your build number as the projectVersion.
  • Default: For Maven projects: <description>; otherwise, “not provided”.

FAQ

Is it possible to trigger analyses on Linux or macOS agents? This is possible from version 1.0 of the SonarCloud extension, in which the extension was fully rewritten in Node.js. The mono dependency was dropped in version 1.3. This is not possible with previous versions of the extension.

How do I break the build based on the quality gate status? Using the SonarCloud quality gate status “pre-deployment gate” in your pipeline, you can prevent release execution and deployment from going ahead if your quality gate status is in the failed state.  Note that you need to enable the Publish Quality Gate Result task in your build pipeline in order for this to work.

Which types of analysis scenarios are supported for .NET projects? Using SonarScanner for .NET, you can build multiple .NET projects between the Prepare Analysis Configuration and Run Code Analysis tasks. You will have full support for issues and code coverage on both, in addition, to pull request analysis. Other types of scenarios are not yet supported.