Building your plugin
To build a plugin, you need Java 8 and Maven 3.1 (or greater). Gradle can also be used thanks to the gradle-sonar-packaging-plugin (note that this plugin is not officially supported by SonarSource).
Sonar plugin API
sonar-plugin-api is a Java API that is used to develop plugins for SonarQube, SonarCloud, and SonarLint.
The API used to be part of SonarQube and released with it, but it is a separate component since v9.5, with its own releases. You can find it here: sonar-plugin-api.
groupId was relocated from
The new coordinates of the dependency are
Create a Maven project
The recommended way to start is by duplicating the plugin example project: https://github.com/SonarSource/sonar-custom-plugin-example.
If you want to start the project from scratch, use the following Maven
To build your plugin project, execute this command from the project root directory:
mvn clean package
The plugin jar file is generated in the project's
The standard way to install the plugin for regular users is to copy the jar artifact, from the
target/ directory to the
extensions/plugins/ directory of your SonarQube installation, then start the server. The file
logs/web.log will then contain a log line similar to:
Deploy plugin Example Plugin / 0.1-SNAPSHOT
Scanner extensions such as sensors are immediately retrieved and loaded when scanning source code.
Debugging web server extensions
- Edit conf/sonar.properties and set:
- Install your plugin by copying its jar file to extensions/plugins.
- Start the server. The line
Listening for transport dt_socket at address: 5005is logged in
- Attach your IDE to the debug process (listening on port 8000 in the example).
Debugging compute engine extensions
Same procedure as for web server extensions (see above), but with the following property:
Debugging scanner extensions
When using the Scanner for Maven, then simply execute:
Advanced build properties
Plugin properties are defined in the file
META-INF/MANIFEST.MF of the plugin jar file.
Most of them are defined through the
<configuration> section of the sonar-packaging-maven-plugin. Some are taken from standard pom nodes Effective values are listed at the end of the build log:
Supported standard pom node properties:
|Maven property||Manifest key||Notes|
|Plugin-Version||(required) Plugin version as displayed in page "Marketplace". Default: |
|Sonar-Version||Minimal version of supported Sonar Plugin API at runtime. For example, if the value is 184.108.40.206, then deploying the plugin on SonarQube versions with |
|Plugin-License||Plugin license as displayed on page "Marketplace". Default |
|Plugin-Developers||A list of developers is displayed on the page "Marketplace". Default: |
|Maven property||Manifest key||Notes|
|Plugin-Key||(required) Contains only letters/digits and is unique among all plugins. Examples: groovy, widgetlab. Constructed from |
|Plugin-Class||(required) Name of the entry-point class that extends |
|Plugin-Name||(required) Displayed in the page "Marketplace". Default: |
|Plugin-Description||Displayed in the page "Marketplace". Default: |
|Plugin-Homepage||Homepage of website, for example https://github.com/SonarQubeCommunity/sonar-widget-lab|
|Plugin-IssueTrackerUrl||Example: https://github.com/SonarQubeCommunity/sonar-widget-lab/issues. Default: |
|Plugin-TermsConditionsUrl||Users must read this document when installing the plugin from Marketplace. Default: |
|Plugin-ChildFirstClassLoader||Each plugin is executed in an isolated classloader, which inherits a shared classloader that contains API and some other classes. By default the loading strategy of classes is parent-first (look up in shared classloader then in plugin classloader). If the property is true, then the strategy is child-first. This property is mainly used when building plugin against API < 5.2, as the shared classloader contained many 3rd party libraries (guava 10, commons-lang, ...) false.|
|Plugin-Base||If specified, then the plugin is executed in the same classloader as |
|Plugin-SourcesUrl||URL of SCM repository for open-source plugins. Displayed on page "Marketplace". Default: |
|Plugin-Organization||The organization which develops the plugin is displayed on the page "Marketplace". Default: |
|Plugin-OrganizationUrl||URL of the organization, displayed on the page "Marketplace". Default: |
|SonarLint-Supported||Whether the language plugin supports SonarLint or not. Only SonarSource analyzers and custom rules plugins for SonarSource analyzers should set this to true.|
|Plugin-Display-Version||The version is displayed in SonarQube administration console. By default it's the raw version, for example, "1.2", but can be overridden to "1.2 (build 12345)" for instance. Supported in sonar-packaging-maven-plugin 220.127.116.112. Default: |
sonar-packaging-maven-plugin supports also these properties:
|Maven property||Manifest key||Notes|
|Copy pom file inside the directory META-INF of generated jar file?||Boolean. Default: |
|Do not copy Maven dependencies into jar file.||Default: |
Other Manifest fields:
Implementation-Build: Identifier of build or commit, for example, the Git SHA1.
94638028f0099de59f769cdca776e506684235d6. It is displayed for debugging purposes in logs when the SonarQube server starts.
SonarQube provides extension points for its three technical stacks:
- Scanner, which runs the source code analysis.
- Compute Engine, which consolidates the output of scanners, for example by:
- computing 2nd-level measures such as ratings.
- aggregating measures (for example number of lines of code of project = sum of lines of code of all files).
- assigning new issues to developers.
- persisting everything in data stores.
- Web application.
Extension points are not designed to add new features but to complete existing features. Technically they are contracts defined by a Java interface or an abstract class annotated with
@ExtensionPoint. The exhaustive list of extension points is available in the Javadoc.
The implementations of extension points (named extensions) provided by a plugin must be declared in its entry point class, which implements
org.sonar.api.Plugin and which is referenced in the
A plugin extension exists only in its associated technical stacks. A scanner sensor is for example instantiated and executed only in a scanner runtime, but not in the web server nor in Compute Engine. The stack is defined by the annotations @ScannerSide, @ServerSide (for a web server), and @ComputeEngineSide.
An extension can call core components or another extension of the same stack. These dependencies are defined by constructor injection:
It is recommended not to call other components in constructors. Indeed, they may not be initialized at that time. Constructors should only be used for dependency injection.
A compilation will not fail if incorrect dependencies are defined, such as a scanner extension trying to call a web server extension. Still, it will fail at runtime when a plugin is loaded.
Plugins are executed in their own isolated classloaders. That allows the packaging and use of 3rd-party libraries without runtime conflicts with core internal libraries or other plugins. Note that since version 5.2, the SonarQube API does not bring transitive dependencies, except SLF4J. The libraries just have to be declared in the
pom.xml with the default scope "compile":
Technically, the libraries are packaged in the directory META-INF/lib of the generated jar file. An alternative is to shade libraries, for example with
maven-shade-plugin. That minimizes the size of the plugin jar file by copying only the effective used classes.
mvn dependency:tree gives the list of all dependencies, including transitive ones.
The core component
org.sonar.api.config.Configuration provides access to configuration. It deals with default values and the decryption of values. It is available in all stacks (scanner, web server, Compute Engine). As recommended earlier, it must not be called from constructors.
Scanner sensors can get config directly from SensorContext, without using constructor injection:
In the scanner stack, properties are checked in the following order, and the first non-blank value is the one that is used:
- System property.
- Scanner command-line (-Dsonar.property=foo for instance).
- Scanner tool ( of scanner for Maven for instance).
- Project configuration defined in the web UI.
- Global configuration defined in the web UI.
- Default value
Plugins can define their own properties so that they can be configured from the web administration console. The extension point
org.sonar.api.config.PropertyDefinition must be used:
Values of the properties suffixed with
.secured are not available to be read by any users. The
.secured suffix is needed for passwords, for instance.
@org.sonar.api.Property can also be used on an extension to declare a property, but
org.sonar.api.config.PropertyDefinition is preferred.
org.sonar.api.utils.log.Logger is used to log messages to scanner output, web server logs/sonar.log, or Compute Engine logs (available from the administration web console). It's convenient for unit testing (see class
Internally SLF4J is used as a facade of various logging frameworks (
java.util.logging). That allows all these frameworks to work at runtime, such as when they are required for a 3rd party library. SLF4J loggers can also be used instead of
org.sonar.api.utils.log.Logger. Read the SLF4J manual for more details.
As an exception, plugins must not package logging libraries. Dependencies like SLF4J or
log4j must be declared with the scope "provided".
Exposing APIs to other plugins
The common use case is to write a language plugin that will allow some other plugins to contribute additional rules (for example, see how it is done for Java analysis). The main plugin will expose some APIs that will be implemented/used by the "rule" plugins.
Plugins are loaded in isolated classloaders. It means a plugin can't access another plugin's classes. There is an exception for package names following pattern
org.sonar.plugins.<pluginKey>.api. For example, all classes in a plugin with the key
myplugin that are located in
org.sonar.plugins.myplugin.api are visible to other plugins.
Serving static resources
myplugin/src/main/resources/static). At runtime, they'll be available from
Versioning and API Deprecation
The goal of this versioning strategy is to:
- Release early, and release often, in order to get quick feedback from the SonarQube community.
- Release stable versions of the SonarQube platform for companies whose main priority is to set up a very stable environment. Even if the price for such stable environments is missing out on the latest, most up to date SonarQube features.
- Support the API deprecation strategy (see next section).
The rules are:
- Every two months (or so) a new version of SonarQube is released. This version should increment the minor digit of the previous version (ex: 8.2 -> 8.3).
- Every eighteen months (or so), a bug-fix version is released and becomes the new LTS. The major digit of the subsequent version is incremented to start a new cycle (ex: 7.9 -> 8.0).
And here is the strategy in action:
API deprecation strategy
The goal of this deprecation strategy is to make sure that deprecated APIs will be dropped without side effects at a given planned date. The expected consequence of such a strategy is to ease the evolution of the SonarQube API by making such refactoring painless.
The rules are:
- An API must be deprecated before being dropped. Furthermore, if the underlying feature is not being dropped, a replacement API must immediately be provided.
- A deprecated API must be fully supported until its drop (For instance the implementation of a deprecated method can't be replaced by
throw new UnsupportedOperationException()).
- If an API is deprecated in version X.Y, this API is planned to be dropped in version (X+1).0. Example: an API deprecated in 9.1 is supported in 9.2, 9.3, and so forth for the entire 9.N cycle; it will be dropped in version 10.0.
- According to this versioning strategy, an API can remain deprecated for up to 18 months, and for as short as 2 months.
- Any release of a SonarQube plugin must at least depend on the latest LTS version of the SonarQube API.
- For each SonarQube plugin there must at least one release on each LTS version of SonarQube, which means at least one release each ~18 months.
- An API is marked as deprecated with both:
- the annotation
- the javadoc tag
@deprecatedwhose message must start with "in x.y", for example:
- the annotation
Starting with v9.5, the API is released independently of SonarQube. You can find the changes for newer releases in its code repository.
sonar-plugin-api.src.main.java.org.sonar.api.resources.Language#publishAllFilesto define whether the files identified with the language should be automatically published to SonarQube.
org.sonar.api.server.rule.RulesDefinitionXmlLoaderis deprecated. Use the
sonar-check-apito annotate rule classes instead of loading the metadata from XML files.
org.sonar.api.Plugin.Context#addExtensions()to add objects to the container.
- All API related to preview/issues analysis mode.
- Coverage types (unit, IT, overall) was removed.
- Resource perspectives. Use methods in
org.sonar.api.profiles.ProfileDefinition.java. Define quality profiles with
org.sonar.api.rules.XMLRuleParser. Use the
sonar-check-apito annotate rule classes.
org.sonar.api.rules.Rule#getId()is deprecated and will always throw UnsupportedOperationException.
- Pico components relying on reflection to have their
stopmethod called. Make your component implements
- The preview/issues mode of scanner has been removed.
PostJobmoved to the project level IoC container.
InputFileFiltermoved to the project level IoC container.
- New annotation
org.sonar.api.scanner.ScannerSideto mark (project level) scanner components.
org.sonar.api.batch.fs.InputProjectto create issues on a project.
org.sonar.api.scanner.ProjectSensorto declare Sensors that only run at the project level.
- The concept of global Sensor is deprecated (use
- Support of scanner tasks was removed.
RulesProfileis no longer available for scanner side components (use
- Allow identity provider to not provide login.
- Allow sensors to report adhoc rules metadata.
org.sonar.api.rules.RuleFinderremoved from scanner side.
sonar-channelremoved from plugin classloader.
- stop support of plugins compiled with API < 5.2.
RulesDefinitionssupports HotSpots and security standards.
org.sonar.api.issue.ProjectIssuessince preview mode is already deprecated for a while.
org.sonar.api.batch.sensor.SensorContext#newExternalIssueto report external issues.
org.sonar.api.batch.sensor.SensorContext#newSignificantCodeto report part of the source file that should be used for issue tracking.
org.sonar.api.server.rule.RulesDefinition.NewRule#addDeprecatedRuleKeyto support deprecated rule keys.
org.sonar.api.batch.scm.ScmProvider#revisionIdto improve branch and PR support.
© 2008-2022, SonarSource S.A, Switzerland. Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution-NonCommercial 3.0 United States License. SONARQUBE is a trademark of SonarSource SA. All other trademarks and copyrights are the property of their respective owners.