Managing quality gates

Quality gates are defined at the organization level and applied at the project level. Each project has one quality gate assigned from among those defined in the organization.

Defining new quality gates for your organization

Every organization comes with the built-in Sonar way quality gate set as the default to be assigned to all new projects. Sonar way is the only quality gate available for a Free plan. See the Subscription plans page for more information.

Though the Sonar way quality gate is suitable for most projects, there are cases where you may want to make adjustments. In those situations, you can create a new quality gate definition and either just make it available to projects in the organization or set it as the default for all new projects.

To create a new quality gate definition in an organization, you must be its administrator on the Teams or Enterprise plan. 

You can copy an existing quality gate, such as the Sonar way, or create a new one, and then adjust it. By default, all new quality gates come with conditions that make them Clean as You Code ready (see below). These conditions can be modified and removed.  

To make changes, go to Your Organization > Quality Gates.

In the example above we see two quality gates defined: the built-in one, called Sonar way, and another custom-defined gate, called Claudia's way.

A quality gate can have conditions on new code, conditions on overall code, both, or neither (though such an empty quality gate is not particularly useful, as it will always report a status of Passed).

Claudia's way, above, consists of six Conditions on New Code and five Conditions on Overall Code.

Conditions can be added to either section by selecting Add Condition. Adjustments can be made to conditions by selecting the edit pen, and conditions are deleted by selecting the trash can.

Conditions define failure

Quality gate conditions are always stated in terms of failure. In other words, if any condition in the quality gate (in either new or overall code) is true, then the quality gate fails.

Deciding on a quality gate

For most cases, we recommend directly using or adapting the built-in Sonar way quality gate.

The Sonar way quality gate places a minimum requirement of an A rating on Reliability, Security and Maintainability, a minimum requirement of 80% Coverage and a maximum of 3% Duplicated Lines of code. This is applied to new code only. There are no conditions on overall code.

This quality gate represents our view of the best way to implement the Clean as You Code methodology, which we strongly recommend as the best way to get the most out of SonarQube Cloud.

Some users may wish to add, remove or adjust the conditions (including adding some on overall code) using the Sonar way as a starting point.

The Add Condition button provides a selection of possible metrics for use in quality gate conditions. Keep in mind as you define your own quality gates, that the ultimate goal is to provide useful feedback to your developers when they look at the quality gate on their project page.

Configuring a quality gate for Clean as You Code

By always committing clean code, you incrementally improve the overall quality of your project, this is the essence of the Clean as You Code methodology.

To guarantee you commit only clean code, you need to configure your quality gates with conditions ensuring that the new code is free of issues, has limited duplication, and is sufficiently covered by tests.

By default, when you create a quality gate, it already comes with the right conditions. The same applies to the default ‘Sonar way’ quality gate.

We recommend configuring all your quality gates for Clean as You Code. To do this, make sure that your quality gates contain the following conditions on new code.

Step 1: Issues

Or

While the three rating conditions help improve the quality of new code, they still allow some technical debt to sneak into your codebase. Instead, using the 0 issues condition will ensure that your new code is completely clean from any issues.

Step 2: Security review, duplication and coverage

You can customize the duplication and coverage conditions to fit your needs. The other conditions should not be edited or removed if you wish to keep your quality gate Clean as You Code ready.

Setting the quality gate for your project

Once an organization administrator has made a new quality gate available in your organization, you can select that quality gate for use in your project.

To select a quality gate for a project, you must be an administrator of that project.

You select the quality gate that you want from the available ones listed in Your Project > Administration > Quality Gates:

If you don’t explicitly select a quality gate for your project, the default set for your organization will be the Sonar way. Usually, this is the Sonar way quality gate, although your Organization Administrator can change this default. To see the Sonar way quality gate, navigate to Your organization > Quality Gates and select the Sonar way Quality Gate.

See this section for information about what might change after a SonarQube Cloud update.