Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท Concepts and Setup

Projects, Branches and Pull Requests

Learn how SonarQube organizes code into projects, project keys, branches and pull requests, how analyses compare to each other, and how to name things well.

SonarQube organizes everything around the project. A project is the result of repeatedly analyzing one codebase. Inside it live branches, pull requests, a history of analyses and the quality gate status. Getting this structure right early saves you from duplicated projects and confusing history, so this lesson explains each piece and the naming rules.

What a project is

A project is identified by its project key, a unique string across the server, for example acme_shop-api. The key is the stable identity: every analysis that uses the same key adds to the same history. The project name is a display label you can change at any time. Keys may contain letters, digits and the characters -, _, . and :, and must contain at least one non-digit.

Conventions that work well:

  • Use a pattern such as team_repository or org_repo, so keys stay unique and sortable.
  • Never reuse a key for a different codebase. History would mix.
  • Do not rename keys casually; you can change a key in the project settings, but every CI job must change too.

In a monorepo you have a choice: one project for everything, or one project per module (each analyzed separately with its own key). Separate projects give per-module gates and history; one project is simpler. Your language scanners and build tools also support multi-module analysis within a single project.

Python Validate a project key (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Branches

The first analysis of a project creates the main branch (named when you created the project, typically main). The main branch is the one the quality gate and dashboards describe by default, and the others are compared with it.

Branch analysis (a Developer Edition and above feature, and part of SonarQube Cloud) lets you analyze release/1.2, feature/login and others as separate lines of history inside the same project. You tell the scanner the branch with -Dsonar.branch.name=feature/login; in many CI integrations it is detected automatically. A branch with no new analyses for a configured time is deleted by housekeeping (30 days by default for non-main branches; check your settings).

Long-lived branches such as release branches keep their issues and measures, and you can set their new code definition separately.

Pull requests

A pull request analysis checks only the changed code of the request against the target branch and reports its own quality gate result. In editions that support it, the result is posted back to your code host (GitHub, GitLab, Bitbucket, Azure DevOps) as a status check and a decoration with the new issues, so reviewers see problems inline. The scanner learns the pull request through properties such as sonar.pullrequest.key, sonar.pullrequest.branch and sonar.pullrequest.base.

Terminal
sonar-scanner \
  -Dsonar.pullrequest.key=482 \
  -Dsonar.pullrequest.branch=feature/login \
  -Dsonar.pullrequest.base=main

Pull request data is temporary: when the request is merged or closed and a cleanup period passes, SonarQube removes it. Only the main branch and long-lived branches keep history.

flowchart LR
  M["main (history, dashboards)"] --> R["release/2.0 (long-lived)"]
  M --> F["feature/login"]
  F --> P["PR #482<br/>analyzes only new code"]
  P -- merge --> M

One project, several lines of history. Only the PR view is temporary.

How an analysis is compared

Each analysis is compared with the previous one on the same branch to decide which issues are new, which were fixed and which stay open. Pull requests are compared with their target branch. This comparison is why a rename or a large move can look like fixed-and-new issues: the engine tracks issues by rule, file, and a hash of the surrounding code to follow them across moves where it can.

The stand-in below mimics a simplified tracker: matching issues in two analyses by (rule, line text), so moved code is not counted as new.

Python Which issues are new, fixed or unchanged? (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Organizations and grouping

Servers with many projects use portfolios (Enterprise Edition) or tags and favorites to group them; SonarQube Cloud adds organizations that bind to a code-host group. In Community Build you organize with naming conventions and tags. Plan names early: it is the one decision that is painful to change later.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What uniquely identifies a project and links successive analyses?

    Analyses that use the same project key accumulate in the same project history.
  2. 2. Which key is valid?

    Keys allow letters, digits and - _ . : and need at least one non-digit; spaces and slashes are illegal.
  3. 3. What does a pull request analysis report on?

    Pull request analysis focuses on the new and changed code relative to the base branch.
  4. 4. Which data is temporary?

    Pull request analyses are removed after the request is closed and a cleanup period passes.

Summary

  • A project is identified by its key; the name is a label.
  • Branch and pull request analysis (Developer Edition and above, or the cloud) give separate histories and per-request gates.
  • Analyses are compared with the previous analysis of the same branch; PRs are compared with the target branch.
  • PR data is temporary; the main branch and long-lived branches keep history.
  • Choose key names deliberately.

Next: Users, Tokens and Permissions