Best practices
Resolve failures caused by new or modified rules
Whenever SonarQube version upgrades, it may introduce rule updates, which are documented in their release notes.
Quality Profiles are groups of SonarQube rules that are applied during code analysis, and these profiles may be updated as part of the upgrade. This means that when you run a scan after the upgrade, you may encounter new findings due to modified or newly added rules.
Even if your Quality Gate conditions, the set of definitions that determine whether your code passes or fails, have not changed, new rule violations can still cause failures. This happens because the updated rules in the Quality Profile may now flag issues that were previously undetected.
To resolve this, we share the following options:
| Option | Description | When to choose | Action required |
|---|---|---|---|
| Fix issue(s) (most recommended) | The best and most sustainable solution. | Always recommended as the first choice. | 1. Review new vulnerabilities or issues flagged by SonarQube. 2. Fix the issues to comply with the updated quality standards. For example, the screenshot below highlights two flagged issues that need resolution.  |
| Assign backup Quality Profile Temporary workaround |
Switch to the previously supported quality profile. | When newly added or changed rules are causing issues and a fix isn’t immediately possible. | For detailed steps, see Assign a backup Quality Profile. |
| Temporarily loosen quality gate conditions (intermediate) | Make temporary adjustments to quality gate conditions. | - Choose this only when it is not possible to fix issues immediately. - Must have a custom quality gate (not a shared/global one). |
1. Submit a Service Request to SHIP-HATS to adjust the quality gate. 2. After resolving the issues, revert the temporary change to ensure code quality standards. Note: If you do not revert the quality gate within 2 weeks, SHIP-HATS team will revert them for you. |
| Bypass quality gate check (least recommended) | Skips quality gate enforcement, allowing the scan to pass even with violations. | Choose this as a last resort when the job must pass without fixing issues or modifying the quality gate. | 1. Set the following variable in your pipeline: QUALITY_GATE_WAIT=false 2. After resolving the issues, revert this setting to ensure code quality standards. For more details, refer to the SHIP-HATS templates repository. |
Custom quality profile
We do not recommend to create custom quality profile. We recommend that you use the default built-in quality profile provided by SonarQube (Sonar Way).
We do not recommend creating custom quality profile by extending an existing quality profile if it does not extend from the default built-in quality profile (Sonar Way).
We do not recommend creating custom quality profile copying an existing quality profile as new rules that are available with each updated SonarQube version will not be automatically added to this custom quality profile.
If you want to create a custom quality profile which either extends an existing quality profile (any profile but Sonar Way) or copies an existing quality profile, the request will be reviewed on a case by case basis. After the custom quality profile is created, you will be responsible for managing the rules updates. You will be granted permission to manage said quality profile yourself.
For more information, refer to the SonarQube Quality profiles documentation.
Optimise code analysis scope
While customising your SonarQube analysis, consider your specific use case to determine if scanning every aspect of your source code is necessary. Instances such as generated code (e.g., XML), source code from libraries, or intentionally duplicated code may not always warrant a detailed analysis.
By default, .xml files are excluded from Enterprise edition scanning. To include xml files in the scanning, refer to the SonarQube FAQs.
Hence, to enhance precision and focus on critical issues, selectively skip aspects of the analysis for these files. This practice helps reduce noise, allowing you to concentrate on the aspects that truly matter for your project.
Additionally, complement your code analysis efforts by integrating other scanning techniques, such as secrets scanning, dependency scanning, and Static Application Security Testing (SAST).
For more information on configuring and customising the behaviour of SonarQube code analysis, refer to SonarQube Documentation.
