Quality gates

Overview

Quality gates enforce a quality policy in your organization by answering one question: is my project ready for release?

To answer this question, you define a set of conditions against which projects are measured. For example:

• No new issues
• Code coverage on new code greater than 80%

See the Defining quality gates section below for more information on defining conditions.

Ideally, all projects will use the same quality gate, but that's not always practical. For instance, you may find that:

• The technological implementation differs from one application to another. For example, you might not require the same code coverage on new code for web applications as you would for Java applications.
• You want to ensure stronger requirements on some of your applications, for example, internal frameworks.

For these reasons, you can define as many quality gates as you need. You can access the Quality Gates page from the top menu. From there, you can define and manage all of your quality gates.

Depending on the configuration of your SonarQube Community Build instance, metrics will affect your quality gates differently in Standard Experience and MQR Mode. See the Changing modes page for more details.

Quality gate permissions

By default, only users with the global Administer Guality Gates permission can edit quality gates. This is set at Administration > Security > Global Permissions.

SonarQube Community Build also allows users with the global Administer Quality Gates permission to give an expert or group of experts permission to manage a specific quality gate. These experts only have permission for that quality gate, not all quality gates. Grant permissions to specific quality gates on the Quality Gate's page (Quality Gates > Your quality Gate name) under the Permissions heading by selecting Grant permissions to a user or a group.

Defining quality gates

Each quality gate condition is a combination of:

• a measure.
• a comparison operator.
• an error value.

For instance, a condition might be

• measure: Blocker issue
• comparison operator: >
• error value: 0

Which can be stated as: No blocker issues.

Use the best quality gate configuration

With a quality gate, you can compare ratings given to your code for (Reliability, Security, Security Review, Maintainability (in MQR Mode) or Bugs, Vulnerabilities, Security Review, Code Smells (in Standard Experience) to the ratings set as thresholds in your quality gate conditions. This will determine whether your code passes the quality gate. Note that while test code quality impacts your quality gate, it's only measured based on the Maintainability and Reliability metrics in MQR Mode and Code Smells and Bugs metrics in Standard Experience. Duplication and security issues are not measured on test code.

You should adjust your quality gates so that they provide clear feedback to developers looking at their project page.

Remember that quality gate conditions must use differential values. For example, there's no point in checking an absolute value such as: Number of Lines of Code is greater than 1000.

Using Sonar way, the recommended quality gate

The Sonar way quality gate is Sonar’s recommended quality gate for your new code, helping you implement the Clean as You Code approach. It is provided by SonarSource, activated by default, and read-only.

This quality gate focuses on keeping new code clean, rather than spending a lot of effort remediating old code.

Conditions

The Sonar way quality gate has four conditions: 

• No new issues are introduced
• All new Security Hotspots are reviewed
• New code test coverage is greater than or equal to 80.0%
• Duplication in the new code is less than or equal to 3.0%

Configuring a quality gate for Clean as You Code

We recommend configuring all your quality gates to make them Clean as You Code ready. You can do this by configuring your quality gate conditions for new code. This helps you ensure that you're not introducing issues in your code.

A quality gate is configured for Clean as You Code when it has the following conditions on new code:

• No issues are introduced (the quality gate fails when the Number of issues is higher than 0)

OR

In MQR Mode:

• Reliability Rating is not worse than A
• Security Rating is not worse than A
• Maintainability Rating is not worse than A

In Standard Experience:

• Bugs Rating is not worse than A
• Vulnerability Rating is not worse than A
• Code Smells Rating is not worse than A

In addition, it ensures that:

• Security Hotspots Reviewed is not less than 100%, meaning that all the security hotspots are reviewed.
• [Configurable] There is a limited amount of Duplicated Lines.
• [Configurable] Coverage of code by tests is sufficient.

For more information on these conditions see the Glossary and Metric definitions pages.

The duplication and test coverage conditions are configurable to your specifications. However, if you wish to remain compliant with Clean as You Code, the other conditions are locked and cannot be edited. 

To ensure that your new code is always clean, we recommend including the No new issues are introduced condition in your quality gate. You can do this by 

• clicking the Review and Optimize Quality Gate if your quality gate is already compliant, or 
• clicking the Review and Update Quality Gate if your quality gate is not compliant.

Upgrading quality gates for Clean as You Code

You can upgrade your quality gate to the Clean as You Code approach by clicking on Review and Update Quality Gate. This improvement will add any of the required conditions for CaYC and leave your additional conditions unchanged.

Quality gate status

The current status is displayed prominently at the top-left of your Project page:

Getting notified when a quality gate fails

Thanks to the notification mechanism, you can be notified when the quality gate status changes. To do so, subscribe to the New quality gate status notification for all projects or a set of projects you're interested in. 

• To receive notifications on all projects, go to My Account > Notifications > Overall notifications and select Quality gate changes on all available projects
• To receive notifications on a per-project basis, go to My Account > Notifications > Notifications per project. From there, select Add a project, search for Your project, and select Quality gate changes.
  • Note that you can also subscribe to manage your project notifications from the Your Project > Project Information > Set notifications menu.

Updating quality gates after changing modes

With the SonarQube Community Build instance admin permissions, you can change the instance's mode from Standard Experience to MQR Mode and vice versa. 

After you change the mode, you may have to update some quality gates, as the modes use different metrics and affect software qualities in different ways. See the Changing modes page for details.

You do not have to update Sonar way quality gates as they are updated automatically for each mode.

When an update to a custom quality gate is available, you will see an update icon on the list of your custom quality gates. 

To update your quality gate:

• Select a quality gate that displays the update icon from the list of quality gates.
• Click on each condition that displays the update icon and go through the update process. You cannot edit conditions until they are updated.

The conditions' metrics will be calculated differently even if the conditions' names persist between the modes. Operator and value will remain unchanged.

Security

Quality gates can be accessed by any user, even anonymous users. All users can view every aspect of a quality gate.

To make changes (create, edit, or delete) to quality gates and quality profiles, you must be granted the Administer Quality Profiles and Quality Gates permissions.

A project administrator can choose which quality gates their project is associated with. See Project settings for more details.