How to add new GitLab Project into SonarQube Server?

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

1. Configure GitLab as a DevOps platform in SonarQube
2. Create the project in SonarQube and bind it to the GitLab repo
3. 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:

1. In SonarQube, go to Administration → DevOps Platform Integrations → GitLab.
2. Click Add Integration (or Configure).
3. 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.
4. 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.):

1. On the SonarQube homepage, click Create Project.
2. Choose Import from DevOps Platforms → From GitLab.
3. Select your GitLab instance (the one you configured).
4. Choose the repository and agree to the project key (or adjust it).
5. 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:

1. Go to Projects → Create Project → Local Project.
2. Enter:
   • Project key: e.g. myteam:my-project (must match what you’ll use in CI).
   • Display name: e.g. My Project.
3. Click Set Up.
4. On the setup page, choose your language and OS; SonarQube will show configuration hints.
5. 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

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

3.2. Add CI variables in GitLab

In your GitLab project:

1. Go to Settings → CI/CD → Variables.
2. 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:

• Create (or update) the project.
• Show issues, metrics, and quality gate status.
• If integration is configured, decorate GitLab MRs with results.

Our company officially represents both Sonar and GitLab,
and provides support for both GitLab and SonarQube, including both hands-on tech issues and methodolgies.
Contact us: sonarqube@almtoolbox.com or call us.

Related Links:

• Our Sonar webpage
• Our GitLab webapge

First release: October 2024.