Understanding quality gates

A quality gate consists of a set of conditions against which the code is measured during analysis. A condition is defined on either new code or overall code. Depending on the result, the code will pass or fail the quality gate, giving developers indications on whether to fix issues or merge the code:

The quality gate status (Passed or Failed) appears with analysis results of the main branch, other branches, and pull requests in the respective project’s page as illustrated below.

Basic principles

Each project is assigned a quality gate. A default quality gate is defined in your organization and applied to all projects not explicitly assigned to a quality gate. 

You may have to use several quality gates depending on your projects:

• 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.
• You should use a quality gate qualified for AI Code Assurance if your project contains AI code.

Two built-in quality gates are provided: Sonar way which is used by default as the default quality gate, and Sonar way for AI Code which is recommended for projects containing AI code. See Quality gates for AI code below. 

You can create your own quality gates, called custom quality gates. 

To create and update custom quality gates, the Administer Quality Gates permission is required. With this permission, you can also associate projects with quality gates. As a project manager, you can associate your project with a quality gate.

Quality gate definition based on conditions

A quality gate is defined through a set of conditions on metrics calculated during the analysis. Each condition applies to a given metric applying either to new code or overall code. If one of the conditions is met, the quality gate fails.

Metrics you can use include:

• Statistics and ratings on detected security, maintainability, and reliability issues.
• Statistics on test coverage.
• Code cyclomatic and cognitive complexities.
• Statistics and ratings on reviewed security hotspots.
• Statistics on duplicated lines and blocks.
• Statistics on code size (the number of various code elements).
• Global statistics on issues.

 Each quality gate condition is a combination of:

• A metric
• A comparison operator
• An error value

For instance, a condition might be

• Metric: Blocker issue
• Comparison operator: >
• Error value: 0

Which can be stated as: No blocker issues.

For more information on the metrics, see Understanding measures and metrics.

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.

The Sonar way quality gate has four conditions: 

• No new bugs are introduced (Reliability rating is A).
• No new vulnerabilities are introduced (Security rating is A).
• New code has limited technical debt (Maintainability rating is A).
• 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%.

Quality gates for AI code

SonarQube Cloud recognizes that AI-generated code requires additional quality standards, and we've created a series of tools to bring AI Code Assurance to your projects. One of these tools includes the Sonar way for AI code quality gate and the option to create your own custom quality gates, specifically qualified for AI code. 

For more information about using all of the Sonar tools for AI Code Assurance, see the Setting quality standards for AI Code Assurance page.

Quality gate computation

Within a specific project, the same quality gate definition is always used for all quality gate status computations. However, the way that the calculations are done differs somewhat between the branches and pull requests. In addition, a fudge factor is used by default during quality gate calculation. In some cases, the quality gate cannot be computed.

Computation for the main branch and long-lived branches

• Both the conditions defined on overall code and conditions defined on new code are applied.
• What counts as new code is determined by the prevailing new code definition setting for the branch, as described in About new code.

Computation for short-lived branches and pull requests

• Only conditions defined on new code are applied.
• And, new code is defined as whatever has changed relative to the target branch, as described in Branch analysis and pull request analysis.

Quality gate fudge factor

The quality gate fudge factor refers to a mechanism where conditions on duplication and coverage are ignored until the number of new lines is at least 20. This is used to avoid overly strict enforcement when dealing with small changes, as minor issues might disproportionately impact the overall quality gate status. 

Currently, you cannot disable the fudge factor.

Not computed status

There are two main reasons why the quality gate may not be computed:

• You have performed only one analysis on your code (the quality gate is computed after the second analysis).
• No new code definition is set up for the project.
  This may only occur for projects created a long time ago since in the current version of SonarQube Server you cannot create a new project without setting up the new code definition. 

If the quality gate has not been computed then the Not computed message is displayed in the place where the quality gate status usually appears as illustrated below. 

The Set New Code Definition button is displayed as well in case no new code definition is set up. To fix this, click the button. For more details on setting up the definition, see About new code page.

Quality gate configured for Clean as You Code

All quality gates should be Clean as You Code ready to help developers ensure that they're not introducing issues in their code. All built-in quality gates are configured for CaYC.

A quality gate configured for CaYC is shown in the UI with a specific icon as illustrated below.

A quality gate is configured for Clean as You Code when it ensures the following:

No new issues are introduced

This is implemented through the following failing condition(s) on new code:

•  Either:
  • The Number of issues is higher than 0.
• Or:
  • Reliability Rating is worse than A.
  • Security Rating is worse than A.
  • Maintainability Rating is worse than A.

Note that 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.

All new security hotspots have been reviewed

This is implemented through the following failing condition on new code:

• Security Hotspots Reviewed is less than 100%.

New code has sufficient test coverage

This is implemented through the following failing condition on new code:

• Coverage is less than X%, where X is configurable.

New code has limited duplications

This is implemented through the following failing condition on new code:

• The duplicated lines density is greater than X%, where X is configurable.

For information on the metrics, see Metric definitions.

Related pages

• Viewing quality gates
• Managing custom quality gates
• Changing the default quality gate of your organization
• Associating a quality gate with projects in your organization
• Getting notified when a quality gate fails
• Managing quality gates for AI code
• Changing the quality gate of your project

DevOps platform integration features:

• Preventing the merge of pull requests on quality gate failure for your project
• Failing your CI pipeline on quality gate failure:
  • Jenkins
  • GitHub Actions
  • Bitbucket Pipelines
  • GitLab CI