Managing the projects of a monorepo

This section explains how to import a monorepo and create the SonarQube projects related to the monorepo. 

This feature is supported in SonarQube with GitHub, GitLab, Bitbucket and Azure DevOps repositories starting in the Enterprise Edition and provided the DevOps platform integration has been properly set up. For the other DevOps platforms, you have to perform the project configuration manually: see the corresponding section in the DevOps platform integration section.

For information about how to add a SonarQube analysis to your monorepo pipeline, see the If you use a monorepo section in the GitLab or GitHub page.

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, SonarQube's support for the monorepo strategy does not depend on the specifics of the monorepo setup. SonarQube 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 SonarQube project.

Monorepo setup in SonarQube

In a monorepo setup, multiple SonarQube projects, each corresponding to a separate monorepo project, are all bound to the same repository. This way:

• The analysis setup of each project in the monorepo is easier. 
• The quality gate status report of pull requests in your DevOps platform is clearly distinguished by project name. 
• The monorepo associated with a project is shown in the SonarQube UI.

Each SonarQube project must have a key unique across SonarQube (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 SonarQube project. We recommend using a pattern that includes your organization name, the SonarQube project name, and an internal reference to the project within the monorepo.

Creating the projects of a monorepo

To create the projects of a monorepo, you need the Create Projects permission in SonarQube.

Proceed as follows:

1. In the top navigation bar of SonarQube, select Projects.
2. In the top right corner, select Create Project > From [DevOps platform]. The Project onboarding page opens.
3. Select Set up a monorepo. The Monorepo project onboarding page opens.
4. Select the monorepo you want to import. The Create new projects section opens with a first project.
5. Check and complete the proposed project name and key.
6. Select Add new project to add additional projects.
7. Once you’ve completed the project list, select Next. The Set up new projects for Clean as You Code page opens.
8. Select the new code definition to be applied by default to the SonarQube projects in the monorepo. Once the projects have been created, you can change the new code definition applying to a given project: see below.
9. Select Create projects. The Projects page opens and displays the newly created projects at the top.

Removing a project from a monorepo

You can remove a project from a monorepo provided you are an administrator of the project:

1. Go to the project page.
2. Select Project settings > General settings > [DevOps platform] Integration and uncheck Enable monorepo support.
   Re-selecting the option brings the project back to its monorepo.

Modifying the new code definition of a project in a monorepo

You can set up a different new code definition for each project in the monorepo provided you are an administrator of the project.  

To set up a new code definition for a given project:

1. Open your project in SonarQube.
2. Go to Project Settings > New Code.