Monorepo support

SonarCloud supports repositories that use the monorepo strategy.

What is a monorepo?

Traditionally, software projects have been organized so that each project is stored within a single, distinct repository of its own.

As software projects have become more complex and interconnected, some organizations have moved to having all their projects in a single large repository. This is called the monorepo strategy.

In a typical monorepo, each project occupies its own directory within the repository and each is independently buildable and deployable, though the exact setup depends on how the procedures that build each project are defined. In general, there are many ways that multiple projects can be arranged within a single repository.

Fortunately, SonarCloud's support for the monorepo strategy does not depend on the specifics of the monorepo setup. SonarCloud relies on the fact that each build procedure can be configured to perform the analysis for its particular project in the repository and send the result to the corresponding SonarCloud project.

Monorepos on SonarCloud

In a standard setup, each SonarCloud project corresponds to a single repository.

In a monorepo setup, multiple SonarCloud projects, each corresponding to a separate monorepo project, are all bound to the same repository.

Note that for the SonarCloud monorepo setup to work properly, you have to build each project separately and use a unique project key for each one.

Each SonarCloud project must have a key unique across SonarCloud (see Analysis Parameters). This is the key that you will use when you configure your CI service. It binds the project in the monorepo to its corresponding SonarCloud project. We recommend using a pattern that includes your organization name, the SonarCloud project name, and an internal reference to the project within the monorepo (for example, myorg_myproject_frontend).

Monorepos on DevOps platforms

Currently, monorepo support is available for GitHub, Bitbucket Cloud, Azure DevOps and GitLab repositories.

Importing a monorepo

Go to the ✚ (plus) menu on the top right of the SonarCloud interface and select Analyze new project.
This will take you to the Analyze projects page
Now click Setup a monorepo (it is a small text link to the right of the where you Choose an organization...).

You will now be on the Analyze monorepo projects page.

Select the organization and then choose the monorepo repository that you want to import.
For each project contained in your monorepo, add a corresponding SonarCloud project by clicking the Analyze new project button in the upper right corner of any page. You have to choose a unique project key for each SonarCloud project. As mentioned above, these are the keys that you will use when configuring your CI service (see below) to bind each monorepo project to its corresponding SonarCloud project.

Choose your new code definition

The next step is to set the New Code Definition (NCD) for your project(s). The NCD is a mandatory step and it defines which part of your code is considered new code. This helps you to focus your attention on the most recent changes to your code and allows you to follow the Clean as You Code methodology.

Select the option by which you want to calculate your new code period. You can choose by Number of days or since the Prevision version. The NCD you choose will apply to all projects in your monorepo.
Then, select Create project.

For more information, check out New code definition.

Convert a standard project to a monorepo

On the analyze projects page you can also add one or more additional project keys to an existing standard project. This will convert that new set of projects to a monorepo configuration (Be aware that monorepo configuration is only supported for CI service, not automatic analysis setups.).

On the analyze projects page you can create a new project for a repository that is already bound to SonarCloud, by selecting the monorepo link on the page. This creates the new project as part of a monorepo setup, and converts your existing project accordingly.

Configuring your CI service

The analysis of a monorepo configuration is only supported for CI service setups, not automatic analysis setups. To perform the configuration, follow the procedure for your CI service:

In the build procedure for each monorepo project, make sure to specify the SonarCloud project key that you designated for it. This provides the binding between the project within the monorepo and the corresponding project in SonarCloud. This enables SonarCloud to correctly process the analysis results and to dispatch pull request decorations back to the DevOps platform for each project individually.

Monorepo is set up

Once the monorepo configuration is complete, when you do an analysis, information from SonarCloud that appears in the pull request view is clearly distinguished by project name.

On this page