SonarQube Projects and Components

In SonarQube, a project represents one codebase — typically one application or service. This topic explains how projects work, how components fit inside them, and how to create and organize projects effectively.

What Is a Project in SonarQube

A SonarQube project is an entry that holds all analysis results for a single repository or application. Every time you run a scan, results go into the corresponding project. The project stores the full history of every scan so you can track quality trends over time.

ORGANIZATION
  |
  +-- Project: mobile-app
  |       |-- Branch: main (latest scan: today)
  |       |-- Branch: feature/login (latest scan: yesterday)
  |
  +-- Project: backend-api
  |       |-- Branch: main
  |
  +-- Project: admin-dashboard
          |-- Branch: main

Project Key

Every project has a unique identifier called a project key. You choose this key when creating the project. The scanner uses this key to associate scan results with the correct project on the server.

Project keys are permanent — changing them breaks history links
Use a consistent naming pattern such as org.company:project-name
Example: com.acme:customer-portal

Creating a Project Manually

Display name (shown in the UI)
Project key (used in scanner configuration)
Main branch name (usually main or master)

CREATE PROJECT FORM
+----------------------------------------------+
| Project display name: [Customer Portal]      |
| Project key:          [com.acme:customer]    |
| Main branch name:     [main]                 |
|                                              |
|              [Set Up]                        |
+----------------------------------------------+

After creating the project, SonarQube generates setup instructions with the scanner command you need to run.

Creating a Project from a DevOps Platform

SonarQube integrates with GitHub, GitLab, Bitbucket, and Azure DevOps. Instead of creating projects manually, you can import repositories directly from these platforms. SonarQube reads the repository list and lets you select which ones to import.

CREATE PROJECT FROM GITHUB
  1. Go to Administration > Configuration > GitHub
  2. Enter your GitHub App credentials
  3. Click "Import from GitHub"
  4. Select your repository
  5. SonarQube creates the project automatically

What Is a Component

Inside a project, a component is any individual unit — a directory, a file, or a function. SonarQube tracks issues at the component level, so you can always see exactly which file and which line contains a problem.

PROJECT: customer-portal
  |
  +-- COMPONENT: src/
  |     |-- COMPONENT: src/auth/
  |     |     |-- COMPONENT: src/auth/LoginService.java  [3 issues]
  |     |     |-- COMPONENT: src/auth/TokenManager.java  [0 issues]
  |     |
  |     |-- COMPONENT: src/api/
  |           |-- COMPONENT: src/api/UserController.java [1 issue]
  |
  +-- COMPONENT: tests/
        |-- COMPONENT: tests/auth/LoginServiceTest.java  [0 issues]

Project Visibility

Projects can be Public or Private:

Public: Any user who can access the SonarQube instance can view the project results, even without logging in (if anonymous access is enabled)
Private: Only users or groups granted explicit permission can view the project

Enterprise teams almost always set projects to private so that scan results are not visible to unauthorized users.

Project Permissions

SonarQube supports fine-grained access control per project. The available permission levels are:

PERMISSION          WHAT IT ALLOWS
-----------         --------------------------------
Browse              View results and issues
See Source Code     View actual code in the Code tab
Administer Issues   Change issue status and assignee
Execute Analysis    Trigger scans (used by CI tokens)
Administer          Change project settings

You can grant these permissions to individual users or to user groups. Managing groups is more practical in large teams because you add users to groups rather than assigning permissions to every person individually.

Project Settings

Each project has its own settings page accessible via the project dashboard. Key settings include:

Quality Gate: Choose which gate applies to this project
Quality Profiles: Select the rule set for each language in this project
New Code Definition: Define what counts as "new code" for this project
Exclusions: Specify files or folders to skip during analysis

Excluding Files from Analysis

You do not always want to analyze every file. Common exclusions include:

Auto-generated code (protobuf files, ORM migrations)
Vendor or third-party libraries checked into the repository
Test fixtures with intentionally bad code

Add exclusion patterns in Project Settings under Analysis Scope:

Source File Exclusions:
  **/generated/**
  **/vendor/**
  **/*.pb.java

Test File Exclusions:
  **/fixtures/**

Deleting a Project

Administrators can delete a project from Administration > Projects > Management. Deleting a project permanently removes all scan history and issue data. This action cannot be undone, so confirm before proceeding.

Project Badges

SonarQube generates embeddable badges you can add to a README file on GitHub. The badge displays the current Quality Gate status — Passed or Failed — as a small image that updates automatically after each scan.

README.md on GitHub
+----------------------------------------------+
| # Customer Portal                            |
|                                              |
| [![Quality Gate](badge-url)](sonar-link)     |
|                                              |
| [Quality Gate Status: PASSED]                |
+----------------------------------------------+

To get the badge URL, go to Project Settings and click the Badges section.

Previous lessons

Back to courses

Next lessons