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.

Requirements

SonarCloud extension for Azure DevOps v3.x.x

Allowable values for the scannerMode required property have changed. Please use the following in your @3 tasks:

• dotnet for the SonarScanner for .NET
• cli for the SonarScanner CLI
• other to integrate with Maven or Gradle

To take advantage of cashing your SonarScanner version, there are a few required inputs for your pipeline. Please see the Caching your SonarScanner download article below, for details.

Version @2 tasks were deprecated in v3.0 and will be dropped in a subsequent release.

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. The pre-deployment gate can be used to prevent the release execution and deployment from going ahead if your quality gate status is in the failed state.
  • 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.

Note that when using the 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.

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 the Advanced section > Additional properties, add the property sonar.cfamily.compile-commands with, as its value, the path to the compile_commands.json file inside the Build Wrapper output directory: sonar.cfamily.compile-commands=<output directory>/compile_commands.json

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.

You must choose the correct image and adapt the correct wrapper depending on the agent OS. See the example below to configure the correct wrapper.

Here's an example .yml file:

trigger:
- main # or the name of your main branch
- feature/*

steps:
- checkout: self
  # Disable shallow fetch
  fetchDepth: 0

# Make Build Wrapper available
- task: Bash@3
  displayName: Download Build Wrapper
  inputs:
    targetType: inline
    script: |
      curl 'https://sonarcloud.io/static/cpp/build-wrapper-linux-x86.zip' --output build-wrapper.zip
      unzip build-wrapper.zip
# Prepare Analysis Configuration task
- task: SonarCloudPrepare@3
  inputs:
    SonarCloud: 'SonarCloud'
    organization: 'mySonarCloudOrganization'
    scannerMode: 'cli'
    configMode: 'manual'
    cliProjectKey: 'YourProjectKey'
    extraProperties: |
      "sonar.cfamily.compile-commands=bw_output/compile_commands.json"
 # Add Command Line task to run your build.
- task: Bash@3
  displayName: Bash Script
  inputs:
    targetType: inline
    script: |
      mkdir build
      cmake -S . -B build
      ./build-wrapper-linux-x86/build-wrapper-linux-x86-64 --out-dir build_wrapper_output_directory cmake --build build/ --config Release
# Run Code Analysis task
- task: SonarCloudAnalyze@3

# Publish Quality Gate Result task
- task: SonarCloudPublish@3
  inputs:
    pollingTimeoutSec: '300'

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 activate the Require approval from additional services feature in Azure DevOps (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:

Caching your SonarScanner download

Azure DevOps allows pipeline caching to improve build performance by facilitating the download of dependencies between pipeline runs. To take advantage of this feature, you must set up a cache task in the Prepare Analysis Configuration task list.

To specify a specific version of the SonarScanner CLI or SonarScanner for .NET, adapt the code sample in the collapsible below to match your version of the relevant scanner. You will see the scanner fetched from the cache rather than being downloaded each time.

- task: SonarCloudPrepare@3
  inputs:
    SonarCloud: 'YourSonarCloudServerEndpoint'
    scannerMode: 'dotnet'
    msBuildVersion: '<YourSonarScannerFullVersionNumber>'
    projectKey: '<YourProjectKey>'

- task: Cache@2
  displayName: Cache SonarScanner
  inputs:
    key: '"SonarScanner" | ".NET" | "$(Agent.OS)"'
    path: '$(Agent.ToolsDirectory)/SonarScanner .NET'

- task: SonarCloudPrepare@3
  inputs:
    SonarCloud: '<YourSonarCloudServerEndpoint>'
    scannerMode: 'cli'
    configMode: 'manual'
    cliVersion: '<YourSonarScannerFullVersionNumber>'
    cliProjectKey: '<YourProjectKey>'
    cliSources: '.'

- task: Cache@2
  displayName: Cache SonarScanner
  inputs:
    key: '"SonarScanner" | "CLI" | "$(Agent.OS)"'
    path: '$(Agent.ToolsDirectory)/SonarScanner CLI'

Previous versions

As new scanner versions are released, previous requirements and/or deprecations will be listed here.

SonarCloud extension for Azure DevOps v2.2.x

Because the current versions of the SonarScanner for .NET or SonarScanner CLI scanners are embedded and depending on your configuration, some additional setup may be required.  

• The SonarScanner for .NET has a new parameter for scanning multiple languages. The Multi-language analysis article has full details. 
• If you want to specify the exact .NET or CLI scanner version, use the msBuildVersion and cliVersion properties. Please check the Using the Prepare Analysis Configuration task article below for details.

When specifying a particular scanner version, internet access is required by the pipelines calling the .NET or CLI scanners:

• Access to github.com is required to download previous versions of the SonarScanner for .NET. If you are white-listing sonarcloud.io, GitHub and its HTTP redirect, objects.githubusercontent.com, should also be whitelisted.
• Access to binaries.sonarsource.com is required to download previous versions of the SonarScanner CLI. If you are white-listing sonarcloud.io, the Sonar binaries should also be whitelisted.

For users running on-premise or using self-hosted agents, the minimum agent version for SonarCloud v2 tasks is 3.218.0.

in v2.0.1

• Version @1 tasks were deprecated and will be dropped in a subsequent release.

SonarCloud extension for Azure DevOps v1.x.x

Version @1 tasks were deprecated in v2.0.1 and will be dropped in a subsequent release.

From version 1.0 of the SonarCloud extension, the extension was fully rewritten in Node.js which means that analyses can be triggered on Linux and macOS agents. The mono dependency was dropped in version 1.3; this is not possible when using previous versions of the extension.

For users running on-premise or using self-hosted agents, the minimum agent version for SonarCloud v1 tasks is 2.114.0.