« Blog Home

How to add new GitLab Project into SonarQube Server?

March 12, 2026 ¬ 11:09 amh.Noa Harel

On SonarQube Server with GitLab (self‑managed or SaaS), the typical flow is:

Configure GitLab as a DevOps platform in SonarQube
Create the project in SonarQube and bind it to the GitLab repo
Generate a token and run the scanner via GitLab CI

Here is a step‑by‑step summary:

1. Configure GitLab integration in SonarQube Server

Do this once per GitLab instance:

In SonarQube, go to Administration → DevOps Platform Integrations → GitLab.
Click Add Integration (or Configure).
Provide:
- Name: e.g. gitlab-self-hosted
- GitLab URL: your self‑hosted URL, e.g. https://gitlab.example.com
- Personal Access Token:
  - In GitLab, create a token for a user with at least Reporter access on the repos you want.
  - Enable the api scope.
  - Paste the token into SonarQube.
Click Connect / Save.
- SonarQube will now list your GitLab repositories.

Optional but recommended:

Ensure Server base URL in SonarQube is set correctly:
Administration → General → Server base URL = your SonarQube URL (e.g. https://sonarqube.example.com) so GitLab can call back for MR decoration.

2. Create and bind the project in SonarQube

Option A: Import from GitLab (with DevOps integration)

This is the recommended way for full integration (MR decoration, etc.):

On the SonarQube homepage, click Create Project.
Choose Import from DevOps Platforms → From GitLab.
Select your GitLab instance (the one you configured).
Choose the repository and agree to the project key (or adjust it).
Click Set Up / Create Project.
- SonarQube creates the project and binds it to the GitLab repo.

Option B: Manual project + later GitLab binding

If you prefer manual creation:

Go to Projects → Create Project → Local Project.
Enter:
- Project key: e.g. myteam:my-project (must match what you’ll use in CI).
- Display name: e.g. My Project.
Click Set Up.
On the setup page, choose your language and OS; SonarQube will show configuration hints.
You can later connect this project to GitLab via the integration page if needed, but for CI-based analysis, the key alignment is enough.

3. Generate a token and configure GitLab CI

3.1. Generate a SonarQube project token

On the project setup page (after creating the project), click Generate a token.
Enter a name like gitlab-ci-scanner.
Click Generate and copy the token.

3.2. Add CI variables in GitLab

In your GitLab project:

Go to Settings → CI/CD → Variables.
Add:
- SONAR_HOST_URL = your SonarQube URL, e.g. https://sonarqube.example.com
- SONAR_TOKEN = the token you generated.
- Optionally SONAR_PROJECT_KEY = your project key if you want to reuse it.

Make sure they are protected/masked as appropriate.

3.3. Create `sonar-project.properties`

In the root of your repo, create:

textsonar.projectKey=myteam:my-project
sonar.projectName=My Project
sonar.sources=.
sonar.sourceEncoding=UTF-8
sonar.qualitygate.wait=true

Adjust:

sonar.projectKey to match the one in SonarQube.
sonar.sources to your source directories if needed.

4. Add a SonarQube analysis job in `.gitlab-ci.yml`

Example using the official Docker image:

textstages:
  - sonarqube

variables:
  GIT_DEPTH: "0"

sonarqube-check:
  stage: sonarqube
  image:
    name: sonarsource/sonar-scanner-cli:latest
    entrypoint: [""]
  script:
    - sonar-scanner
      -Dsonar.host.url=$SONAR_HOST_URL
      -Dsonar.token=$SONAR_TOKEN
      -Dsonar.projectKey=$SONAR_PROJECT_KEY
  allow_failure: true
  only:
    - merge_requests
    - master
    - develop

Key points:

Use sonar.token (not the deprecated sonar.login).
Set GIT_DEPTH: "0" so the scanner can fetch full history.
sonar.qualitygate.wait=true in the properties file will block the pipeline if the quality gate fails (optional but common).

After you push these changes and run the pipeline, SonarQube will: