Infra Notes

SonarQube quality gate failed in GitHub Actions: debug the gate

Diagnose a SonarQube quality gate failure in GitHub Actions by separating scanner execution, analysis processing, new-code conditions, and pipeline enforcement.

Published

DevSecOpsSonarQube Quality GateGitHub ActionsCode CoverageCI Pipeline

Problem

A GitHub Actions job reports that the SonarQube quality gate failed, timed out, or cannot be found. A successful scanner upload only proves the analysis was submitted; the server still processes it and evaluates the project’s assigned gate.

Quick answer

Separate the pipeline into four checkpoints:

  1. Build and tests produced the expected source and coverage artifacts.
  2. The scanner analyzed the intended project key, branch, and revision.
  3. SonarQube completed its background task.
  4. The assigned quality gate evaluated the expected new-code conditions.

Open the analysis in SonarQube and inspect the failed gate conditions. Do not rerun the workflow until you know whether the failure is a real issue, missing report, wrong analysis context, or processing problem.

Verify scanner context

Review scanner output for server URL, project key, source paths, exclusions, branch or pull-request parameters, and the dashboard URL. Confirm the action is not analyzing a different project because a copied repository secret or property retained an old key.

The scanner needs source history for correct new-code and blame information. Avoid shallow or incomplete checkouts when the integration requires history.

Coverage appears as zero

SonarQube generally imports a coverage report produced by the language test tool; it does not generate coverage by itself. Confirm:

  • Tests ran before the scanner.
  • The report exists inside the runner workspace.
  • The scanner property points to the correct relative path.
  • Source paths in the report correspond to the checked-out repository.
  • The report format matches the analyzer’s documented format.

List file names and sizes for diagnosis, but do not print reports containing sensitive paths or test data into public logs.

Gate failed versus gate unavailable

A gate status of ERROR means one or more conditions failed. Fix the new-code issue or follow the documented review process for security hotspots.

A timeout or missing status may mean the background task is queued or failed. Inspect Administration → Projects → Background Tasks and the Compute Engine logs if you operate the server. Increasing the CI wait timeout is appropriate only when processing is healthy but legitimately takes longer.

Keep enforcement explicit

For GitHub pull requests, use the integration recommended for your SonarQube edition and workflow. Whether enforcement happens through a blocking workflow step or required status check, protect the target branch so failed gates cannot be bypassed accidentally.

Do not weaken the organization-wide gate to make one legacy repository pass. Prefer a new-code strategy that improves current changes while historical debt is managed separately.

Prevention

Centralize scanner configuration, pin action versions, validate coverage artifacts before upload, use unique project keys, monitor background-task health, and document who owns quality-gate policy.

This fits the broader DevSecOps pipeline with SonarQube, OWASP ZAP and Nuclei. For dependency scanning, read Scan dependency CVEs early with Syft and Grype.

References