IntelliJ | Team features | Connected Mode

On this page

Connected Mode

Connecting SonarLint to SonarQube or SonarCloud is the first step in setting up the Sonar Solution, to take advantage of having consistent issues reported on both sides. Setting up Connected Mode will permit the transmission of information SonarLint needs, such as URLs and user credentials or file exclusions and marked issues, to communicate with SonarQube or SonarCloud. When binding your local workspace folder to your SonarQube or SonarCloud project(s), SonarLint will try to match, as much as possible, the same rules and settings as found on the server.

While in Connected Mode, SonarLint receives notifications from SonarQube/SonarCloud about your Quality Gate changes and new issues. Smart notifications can be enabled or disabled from the UI while creating or editing the connection settings. 

Benefits

Free and open-source versions of SonarQube and SonarCloud are available to work in Connected Mode. In SonarCloud, it’s always free to analyze your publicly accessible projects; paid plans are required only if linking to a private repository.

Prerequisites and supported languages

Having a SonarQube 8.9+ project or a SonarCloud project is required to run SonarLint for IntelliJ in Connected Mode. In addition to the published languages on the Rules and languages page, you can unlock Scala, Swift, and PL/SQL rules when using Connected Mode.

Branch awareness

Branch awareness allows SonarLint to consider the branch currently checked out in the IDE and synchronize it with the most appropriate branch from the server; we call this branch matching.

In Connected Mode, SonarLint synchronizes some data from the issues that were found on the server, such as the issue's status and resolution. It is important that SonarLint knows on which branch the user is at that moment in order to sync the local analysis with the correct branch analyzed by the server.

SonarLint for IntelliJ only supports git and the git branch name with regard to branch matching, using the git4idea client shipped by JetBrains. If SonarLint’s branch awareness algorithm fails to detect a best match, taint vulnerabilities and issue suppressions will be pulled from the main branch by default.

Checking which branches are analyzed on the server

In SonarQube, open the highlighted drop-down list shown below (as it looks in SonarQube) for a list of analyzed branches and pull requests.

A view of your analyzed branches and pull request in SonarQube.

To analyze branches other than master|main , please check the SonarQube or SonarCloud documentation about branch analysis.

How SonarLint selects which branch to sync

SonarLint deploys these three methods to choose which branch (in SonarQube or on SonarCloud) to sync with the local analysis.

Exact match

Branches with the same name are considered the same branch. If the branch that is currently checked out locally is analyzed on the server, SonarLint will pick this branch for synchronization. 

Closest branch

SonarLint will consider all local branches that also exist on the server. For each branch, SonarLint will compute the distance between the current HEAD and the branch by the count of commits. The closest branch will be kept. In case the number of commits is the same for two or more branches and the main branch is among them, it will be preferred; else the tie will be broken with a random choice (from the list of equidistance branches).

Default to main branch

All other cases will default to the branch marked as "main" on the server. For example, if there is an error in reading the branch, or if there is no Git repo, SonarLint will default to the main branch.

Long and short-lived branches

When using Connected Mode with SonarCloud, issues on short-lived branches are not synchronized. When an issue is marked in SonarCloud accepted or false positive on a short-lived branch, SonarLint will still show that issue in the IDE.

SonarQube does not distinguish between long- and short-lived branches therefore, all issue resolutions are recognized.

Connection setup

SonarLint for IntelliJ provides a connection wizard to help you set up Connected Mode with SonarQube or SonarCloud:

Automatic setup

SonarQube 10.4+ offers the easiest way to set up Connected Mode: simply use the Open in IDE feature from SonarQube. You must trust the SonarQube server to store a token for the connection, and it's best if you already have the project open in your IDE. 

Check the Troubleshooting article if something doesn’t work right or follow the instructions below to manually create a SonarQube connection.

Create a new SonarQube Connection

1. Open IntelliJ settings, find the Tools > SonarLint entry, and select + to open the connection wizard. 

Choose SonarQube and add server details to set up your connection with SonarLint.

2. Enter a name for this connection. When you select SonarQube, you will need to enter the server URL before selecting Next to proceed. The default URL is http://localhost:9000, but your URL might differ.

3. On the window, choose your preferred authentication method:

  • Token: generate a user token in your SonarQube instance. This is the preferred way to avoid the compromise of your username & password. In SonarQube, go to https://<your-sonarqube-url>/account/security/ to generate a new user token.
  • Username + Password: this method can be used for a SonarQube connection only. It lets SonarLint use your credentials directly but is not the recommended method due to potential security risks.

The final steps involve binding your local project to the project on the server.

Create a new SonarCloud Connection

1. Open IntelliJ settings, find the Tools > SonarLint entry, and select + to open the connection wizard. 

Choose SonarCloud and add server details to set up your connection with SonarLint.

2. Enter a Connection Name for this connection and select SonarCloud. Connection Name is a friendly name for your connections.

3. You will be prompted to add a user Token generated by SonarCloud. If you don't already have a token, clicking the Create token button will open the https://sonarcloud.io/account/security page in your default browser where you can select Generate Token in SonarCloud. 

4. Select the SonarCloud Organization that you want to connect to (you can also select any public organization). 

5. SonarCloud can push notifications to developers. You can decide whether or not to subscribe in the SonarCloud UI.

6. Validate the connection creation by selecting Finish at the end of the wizard.

7. Save the connection in global settings by clicking OK.

The final steps involve binding your local project to the project on the server.

Project binding

Once Connected Mode is established, you must bind your IDE project to a SonarQube or SonarCloud project.

Select Bind project to SonarQube / SonarCloud to start the next step in setting up Connected Mode.

1. Open IntelliJ > Settings... and find the Tools > SonarLint > Project Settings entry (shown above).

2. Select Bind project to SonarQube/SonarCloud and choose the previously created connection name in the dropdown list

3. Enter the project key as it is configured on SonarQube/SonarCloud. You can also select it by using Search in list...:

You can enter your Project key directly into the field, or use the search function to find it in a list of projects in your Organization.

Override binding for modules

In IntelliJ additional modules can be imported into a project, e.g. via the 'Project Structure' menu. This is often used for example to group together the back-end and the front-end parts of an application into the same project. As those components might be analyzed separately, SonarLint lets users bind modules to different projects.

1. In the IntelliJ settings, find the Tools > SonarLint > Project Settings entry. Alternatively, you can select the Configure SonarLint tool icon from any of the SonarLint view windows to access the Project Settings menu.

2. Make sure a binding is configured at the project level (see the previous section). Note: this will be the default binding for all modules that have no overridden binding.

3. In the 'Override binding per module' section, click on the + sign and choose the module.

SonarLint gives you the option to override your binding module, if you want.

Troubleshooting Connected Mode

See the Troubleshooting page for details to look at when your SonarLint analysis does not match what you see in SonarQube or SonarCloud.

SonarLint-SonarQube version support policy

SonarLint enables users to establish a connection to the latest SonarQube version and to the latest LTS version. When a new LTS version is released (approximately every 18 months), we still enable connecting SonarLint to the previous LTS version for a certain period of time (currently 12 months after the latest LTS release) to allow enough time for organizations to upgrade their SonarQube version. 

For more information about long-term support of SonarQube, check out our page describing "what is an LTS". And, to review IDE-specific requirements, please check the respective pages of the documentation as listed in the next paragraph.

⚠️ The 8.9LTS reached its support expiration date (in November ’23).

Notifications

Connected Mode allows SonarQube to send smart alerts to individuals or teams as soon as something appears on the server that something failed, when new issues are discovered or when the Sonar Quality Profile is updated, for example. With everyone in the loop, issues can be addressed promptly, improving the overall software quality and delivery. The notification will include a link to call back to SonarQube or SonarCloud where you can learn more about the issues that were introduced. 

You'll receive smart notifications in your IDE when:

  • the quality gate status of a project open in your IDE changes (see the SonarQube or SonarCloud documentation for details about using quality gates in your project)
  • a SonarQube or SonarCloud analysis raises new issues that you've introduced in a project open in your IDE

You can activate or deactivate smart notifications in SonarLint on the IDE side on a server-by-server basis.

Sonar Smart Notifications are available in all editions of SonarQube and SonarCloud.

More on how to manage Smart Notifications in SonarLint for IntelliJ will be coming soon...

© 2008-2024 SonarSource SA. All rights reserved. SONAR, SONARSOURCE, SONARLINT, SONARQUBE, SONARCLOUD, and CLEAN AS YOU CODE are trademarks of SonarSource SA.

Creative Commons License