Introduction to quality gates

Quality gates enforce a quality policy for the results of code review and analysis in your organization by answering one question: is my project ready for release?

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 appears with analysis results of the main branch, other branches, and pull requests in the project’s Overview page as illustrated below.

Basic principles

Each project is assigned a quality gate. A default quality gate is defined in your instance 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. 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 and allow another user to administer a given custom quality gate. 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.

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. By default, the quality gate fudge factor is enabled.

This can be changed:

• At the global level (in Administration > configuration > General Settings >  General > Quality Gate > Ignore duplication and coverage on small changes).
• At the project level. 

The project-level has precedence over the global-level configuration.

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.

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 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%

Sonar way for AI Code

The built-in quality gate Sonar way for AI Code is recommended for projects that contain AI code. You can also create your custom quality gates and qualify them for AI Code Assurance. For more information, see Standards for AI-generated code.

Sonar way for AI Code is shown below. A specific icon is used to indicate that the quality gate is qualified for AI Code Assurance. 

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. 

Computation for 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 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 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. By default, the quality gate fudge factor is enabled.

This can be changed:

• At the global level (in Administration > Configuration > Genaral Settings > General > Quality Gate > Ignore duplication and coverage on small changes).
• At the project level. 

The project-level has precedence over the global-level configuration.

Related pages

• Viewing quality gates
• Managing custom quality gates
• Changing the default quality gate
• Associating projects with a quality gate at the global level
• Getting notified when a quality gate fails

DevOps platform integration features:

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