SonarQube Custom Rules and Plugins
SonarQube ships with thousands of built-in rules, but some organizations need checks that go beyond the defaults — project-specific naming conventions, internal framework usage patterns, or compliance requirements unique to their industry. This topic explains how to extend SonarQube with plugins and custom rules.
Ways to Extend SonarQube
EXTENSION METHOD BEST FOR --------------------- ------------------------------------------- Install a plugin Add rules for a new language or framework Write a custom plugin Enforce company-specific coding standards Use external analyzers Connect third-party tools (Checkstyle, PMD) Template rules Quickly create rule variants from built-ins
The SonarQube Marketplace
SonarQube has a built-in plugin marketplace. Administrators access it at Administration > Marketplace. The marketplace lists both official Sonarsource plugins and community plugins.
MARKETPLACE PAGE +----------------------------------------------+ | [Installed] [Available] [Updates] | | | | Available Plugins: | | - SonarKotlin Kotlin language support | | - SonarSwift Swift language support | | - SonarAbap SAP ABAP language support | | - Checkstyle Java style rules from | | Apache Checkstyle | | - PMD Java analysis from PMD | | [Install] | +----------------------------------------------+
After installing a plugin, restart SonarQube to activate it. New rules from the plugin appear in the Quality Profiles for the relevant language.
Installing a Plugin Manually
Some plugins are not listed in the marketplace. Download the plugin JAR file and place it in the extensions/plugins directory inside your SonarQube installation:
/opt/sonarqube/
extensions/
plugins/
sonar-checkstyle-plugin-10.x.jar <-- place plugin here
Restart SonarQube after placing the file. The plugin loads on startup.
Template Rules
Template rules are a fast way to create custom rules without writing any code. Some built-in rules act as templates — they define a pattern but let you fill in the specific values.
Example: Custom Template Rule for Forbidden Method Calls
Suppose your team wants to flag any use of the internal method LegacyDB.connect() because it has been deprecated in favor of a new data access layer.
- Go to Rules in the top navigation
- Search for the template rule "Track uses of disallowed methods"
- Click Create to make a rule from this template
- Fill in the method name:
LegacyDB#connect - Set severity: Major
- Set the message: "Use DataAccessLayer.connect() instead of LegacyDB.connect()"
- Activate the new rule in your Quality Profile
TEMPLATE RULE: Track uses of disallowed methods +----------------------------------------------+ | Name: No LegacyDB.connect usage | | Method: LegacyDB#connect | | Message: Use DataAccessLayer.connect() | | Severity: Major | | Language: Java | +----------------------------------------------+ Result: Every call to LegacyDB.connect() in the codebase is now flagged as a Major issue.
Writing a Custom Plugin (Overview)
For rules that cannot be created from templates, teams write a custom SonarQube plugin in Java. The plugin implements a check class that SonarQube calls when analyzing each file.
Custom Plugin Structure
my-sonar-plugin/
pom.xml Maven build file
src/main/java/
com/acme/sonar/
MyPlugin.java Plugin entry point
MyRulesDefinition.java Declares the rules
checks/
NoSystemExitCheck.java One check per rule
src/main/resources/
com/acme/sonar/
rules/
NoSystemExitCheck.html Rule description page
NoSystemExitCheck.json Rule metadata (severity, tags)
Example Check: Forbid System.exit()
Calling System.exit() in a web application immediately kills the JVM and takes down the entire server. This custom check prevents developers from using it:
// NoSystemExitCheck.java
@Rule(key = "NoSystemExit")
public class NoSystemExitCheck extends IssuableSubscriptionVisitor {
@Override
public List<Tree.Kind> nodesToVisit() {
return Collections.singletonList(Tree.Kind.METHOD_INVOCATION);
}
@Override
public void visitNode(Tree tree) {
MethodInvocationTree mit = (MethodInvocationTree) tree;
if (isSystemExit(mit)) {
reportIssue(tree, "Do not call System.exit() in application code.");
}
}
private boolean isSystemExit(MethodInvocationTree mit) {
return mit.symbol().name().equals("exit") &&
mit.symbol().owner().name().equals("System");
}
}
Building and Deploying the Plugin
# Build the plugin JAR mvn clean package # Copy to SonarQube cp target/my-sonar-plugin-1.0.jar \ /opt/sonarqube/extensions/plugins/ # Restart SonarQube bin/linux-x86-64/sonar.sh restart
After restart, the custom rule appears under Rules with the tag you assigned. Activate it in a Quality Profile to start enforcing it.
Integrating Checkstyle with SonarQube
Checkstyle is a popular Java linting tool with many style rules that SonarQube does not include by default. The SonarQube Checkstyle plugin reads your existing checkstyle.xml configuration and imports all violations as SonarQube issues.
WORKFLOW WITH CHECKSTYLE
|
+-- Build runs Checkstyle
| Generates: target/checkstyle-result.xml
|
+-- SonarScanner reads the XML report
| sonar.java.checkstyle.reportPaths=
| target/checkstyle-result.xml
|
+-- Issues appear in SonarQube dashboard
as Code Smell issues from Checkstyle rules
Integrating PMD with SonarQube
PMD performs deep Java code analysis covering error-prone patterns, performance issues, and best practices. The SonarQube PMD plugin works the same way as Checkstyle integration:
sonar.java.pmd.reportPaths=target/pmd.xml
Keeping Custom Plugins Updated
Custom plugins need to be rebuilt and redeployed whenever you upgrade SonarQube to a major version. Each SonarQube major release may update the plugin API. Check the SonarQube upgrade notes to see if your plugin's dependencies need updating before you upgrade the server.
PLUGIN COMPATIBILITY CHECK
SonarQube version: 10.x
Plugin API dependency: sonar-plugin-api 10.x
|
Your plugin pom.xml:
<sonar.version>10.x</sonar.version>
|
Must match or plugin will not load