Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 37 ยท Projects and Practice

Project: Put a Quality Gate on a Repository, Start to Finish

Follow a complete project: create a SonarQube project, configure scanner properties, import coverage, run CI, tune a quality gate, and enforce it on pull requests.

In this project you take a small web API repository from "no quality checks" to "pull requests cannot merge unless the SonarQube gate passes". You will write the configuration files, plan the new code period, decide gate conditions, and build a runnable checklist that audits your plan. Because SonarQube cannot run on this site, the steps you perform on your own server are listed precisely, and the TryIts are stand-ins that validate your decisions.

The scenario

The repository orders-api is a Node.js service (TypeScript, Jest tests) with 8,000 lines of source. It has some tests, no static analysis, and the team merges directly. You are the person asked to make quality visible without stopping delivery. The server is SonarQube Developer Edition at https://sonar.example.com, with GitHub as the code host.

Step 1: define success

Before touching any tool, write down what "good" means so that you can set the gate from facts:

  1. New code must have no new issues, all new hotspots reviewed, at least 80% coverage on new code and at most 3% duplicated lines (the Sonar way idea).
  2. Old code is not cleaned in this project; we only stop new debt.
  3. Merges to main require a green gate.

Step 2: create the project and token

On the server:

  1. Projects > Create project > GitHub; select orders-api. (If the integration is not set up, use Manually and enter orders-api as the key.)
  2. Choose With GitHub Actions as the analysis method. The wizard shows the secrets to set.
  3. Generate a project analysis token.
  4. In GitHub add the secrets SONAR_TOKEN and SONAR_HOST_URL.

Step 3: configure the scanner

Create sonar-project.properties at the repository root:

PROPERTIES
sonar.projectKey=orders-api
sonar.projectName=Orders API
sonar.sources=src
sonar.tests=src
sonar.test.inclusions=**/*.test.ts
sonar.exclusions=**/generated/**,**/migrations/**
sonar.coverage.exclusions=**/*.test.ts,**/main.ts,**/*.dto.ts
sonar.javascript.lcov.reportPaths=coverage/lcov.info
sonar.sourceEncoding=UTF-8

Each line has a reason: tests are declared so they are not counted as production code, generated and migration files are not analysed, and bootstrap and DTO files are excluded from coverage because testing them adds no value.

Step 4: workflow

.github/workflows/sonar.yml (modelled on GitHub Actions analysis):

YAML
name: SonarQube
on:
  push: { branches: [main] }
  pull_request: { types: [opened, synchronize, reopened] }
jobs:
  analyse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - run: npx jest --coverage --coverageReporters=lcov
      - uses: SonarSource/sonarqube-scan-action@v5
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
      - uses: SonarSource/sonarqube-quality-gate-action@v1
        timeout-minutes: 5
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

Step 5: set the new code period

In the project: Project Settings > New Code. Options include Previous version, Number of days, Reference branch and a specific analysis. For a team that merges small PRs to main, Reference branch = main keeps new code meaningful in pull requests. For a project with release versions, "Previous version" matches release cycles better. Pick one and note the reason in the repository README.

Step 6: baseline run and the legacy debt

Push to main. The first analysis finds all the old problems. Expect hundreds of issues. This is where the Clean as You Code idea saves the project: the gate judges only new code, so the baseline does not block anyone. Record the starting measures (bugs, vulnerabilities, code_smells, sqale_index, coverage) for later comparison.

Step 7: tune the gate

Start with the built-in Sonar way. If it is too strict for the first month, copy it (built-in gates cannot be edited) and loosen one condition, for example coverage on new code at 60% for a month, then raise it. Assign the copy to the project in Project Settings > Quality Gate. Document each change with a date. Do not drop the hotspot condition; reviewing is cheap and security-relevant.

Step 8: enforce

In GitHub Settings > Branches (or rulesets) require the SonarQube check on main, and require pull requests. Test with a branch that adds an unused variable and an untested function: the check should fail and show the new issues on the PR.

Stand-in: dry-run the gate with your numbers

Before enabling enforcement, run your own PR measures through a copy of the gate. This helps you spot a threshold that would block everything.

JS Stand-in: dry-run a candidate gate on sample PRs

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

No output.

If the pass rate is near zero, the gate is too strict for the team's current habits, and people will look for ways around it. A gate that most healthy PRs pass and bad ones fail is calibrated.

Stand-in: rollout checklist

Use this tracker to follow the project. Mark steps as done and see what is left.

JS Stand-in: rollout tracker

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

No output.

What to do after launch

  • Review the first two weeks of failed PRs to find noisy rules; tune the quality profile instead of ignoring the gate.
  • Hold a 30-minute session to review hotspots with the team (see Reviewing security hotspots).
  • Add a monthly report using the Web API.
  • Raise the thresholds gradually, never in the same week you roll out.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why can the gate be introduced on a messy codebase without blocking everyone?

    Clean as You Code applies conditions to new code, so legacy issues do not block PRs.
  2. 2. A built-in gate is too strict for month one. What do you do?

    Built-in gates are read-only; copy and customize.
  3. 3. Which step actually makes a failing gate block merging?

    Branch protection on the code host enforces the status.
  4. 4. Why exclude *.dto.ts from coverage?

    Pure data holders add little value to coverage, so excluding them keeps the number meaningful.

Summary

  • Define goals, then create the project, token, properties file and workflow.
  • Choose a new code period that matches your branching, record a baseline, then tune a copied gate.
  • Dry-run the gate on sample PRs to calibrate; enforce with a required check.
  • Keep improving: review noise, hotspots and trends after launch.

Next: Project: a Clean as You Code workflow