Gcovr Summary Template

The gcovr-summary.yml template provides a standardized workflow for aggregating coverage reports from multiple test jobs (Meson Test Template) into a single summary report in GitLab CI. It merges coverage data across architectures, generates visualizations, and produces HTML and Cobertura reports for CI dashboards.

It is particularly useful for applications and libraries which contain large amounts of architecture-specific code.

Overview

This template enables you to:

Collect coverage reports from multiple test jobs and merge them into a unified summary.
Generate Cobertura XML and HTML coverage reports for visualization.
Integrate with GitLab’s coverage reporting (total coverage figure and detailed coverage change in merge requests).

Usage in CI

This template is included in CI pipelines as the final stage to define a summary job that runs after all relevant test jobs have completed. The job will automatically discover coverage JSON files, merge them, and publish summary artifacts. See Examples for example usage.

Note

The summary stage doesn’t need to depend on all test jobs, only the ones that actively contribute to the coverage figure.

Also, at the moment, coverage is collected only for GNU toolchain builds, so there is no need to include dependence on LLVM test jobs.

Inputs

The template accepts the following inputs:

Gcovr

gcovr_flags: Additional flags passed to the Gcovr tool. Default: "".

CI Job

extends: Array of jobs to extend this job template. Must include an OCI image template (see Top-level Requirements) and can include target activation rule based on target activation pattern.

Note

The gcovr-summary job uses linux-native-amd64 target, so in case you use the default activation pattern, remember to have it always active, otherwise the summary won’t run.

Default: [.ci-multiplatform-base].
job_name_prefix: Prefix for the job name. Useful for disabling or customizing jobs. Default: "".
job_name_suffix: Suffix for the job name. Default: "".
needs: Optional needs array allowing to execute this job as soon as all relevant stages (i.e., the ones which produce coverage report and actively contribute to the increase of coverage) are completed.

When specifying dependencies for jobs using parallel matrices, ensure the following:
- Mark dependent jobs as optional if you use activation rules based on targets.
- Select only TOOLCHAIN=gnu from the parallel matrix to include relevant coverage jobs.
- When referencing jobs with parallel matrix variables, list all variables in the exact order as declared in the test stage. Refer to the GitLab CI documentation for details.
Example:
```
- job: test:linux-native-amd64
  optional: true
  parallel:
    matrix: [TOOLCHAIN: [gnu]]
- job: test:linux-native-arm64-v8
  optional: true
  parallel:
    matrix: [TOOLCHAIN: [gnu]]
- job: test:linux-native-riscv64
  optional: true
  parallel:
    matrix: [TOOLCHAIN: [gnu]]
```
Default: [test:linux-native-amd64].
stage: CI stage name for the job. Default: summary.
runner_tag: GitLab runner tag for this job. Default: "".

Job Structure

Each job created by the template:

Discovers and collects coverage JSON files from previous test jobs.
Merges coverage data using gcovr and generates Cobertura XML and HTML reports.
Publishes coverage reports and input files as CI artifacts for visualization and further processing.

Artifacts

The summary job produces the following artifacts:

All input coverage JSON files from coverage/
Cobertura XML report: coverage/summary/coverage.xml (used for GitLab coverage visualization)
HTML coverage report: coverage/summary/coverage.html

In order to generate coverage reports you need to enable them in the build stage (Meson Build Template) for GNU toolchain jobs by leaving enable_gnu_coverage enabled and executing the test stage (Meson Test Template). All of this requires an OCI image with all required tools built in OCI Images or by using the Pre-built Images.

Examples

Below is an example job definition using the template syntax:

spec:
  inputs:
    ci_path:
      description: Path to the gcovr-summary component with branch name.
      type: string
      default: gitlab.com/riseproject/ci/ci-multiplatform/gcovr-summary@main
    runner_tag_amd64:
      description: Regular x86 runner.
      type: string
      default: "saas-linux-medium-amd64"
---

include:
  - component: $[[ inputs.ci_path ]]
    inputs:
      runner_tag: $[[ inputs.runner_tag_amd64 ]]
      needs:
        - job: test:linux-native-amd64
          optional: true
          parallel:
            matrix: [TOOLCHAIN: [gnu]]
        - job: test:linux-native-arm64-v8
          optional: true
          parallel:
            matrix: [TOOLCHAIN: [gnu]]
        - job: test:linux-native-riscv64
          optional: true
          parallel:
            matrix: [TOOLCHAIN: [gnu]]

For a full example, see Meson Project Example.

Another example is in the Pixman project in .gitlab-ci.d/04-summary.yml file.