# Source: https://docs.datadoghq.com/code_coverage/monorepo_support.md

---
title: Monorepo Support in Code Coverage
description: Learn how Code Coverage supports large monorepos
breadcrumbs: Docs > Code Coverage > Monorepo Support in Code Coverage
---

# Monorepo Support in Code Coverage

{% callout %}
# Important note for users on the following Datadog sites: app.ddog-gov.com

{% alert level="danger" %}
This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site). ().
{% /alert %}

{% /callout %}

{% callout %}
##### Join the Preview!

Code Coverage is in Preview. This product replaces Test Optimization's [code coverage](https://docs.datadoghq.com/tests/code_coverage) feature, which is being deprecated. Complete the form to request access for the new Code Coverage product.

[Request Access](http://datadoghq.com/product-preview/code-coverage/)
{% /callout %}

## Overview{% #overview %}

For large monorepos containing multiple projects or components, or where multiple teams collaborate, viewing code coverage data for the entire repository may not provide actionable insights. Code Coverage supports splitting coverage data by services and code owners, allowing you to:

- View total coverage, patch coverage, and detailed coverage data for individual services, components, or code owner teams within a monorepo
- Set up PR gates that apply to specific services or code owners
- Track coverage trends for individual services and code owner teams over time

Code Coverage automatically calculates separate coverage metrics for each service and code owner based on the file paths that belong to that service or are owned by that team.

## Ways to split coverage data{% #ways-to-split-coverage-data %}

Code Coverage provides two ways to split coverage data in a monorepo:

### By service{% #by-service %}

1. **[Software Catalog](https://docs.datadoghq.com/service_catalog/) integration** (recommended): Automatically use service definitions from Datadog Software Catalog
1. **Manual configuration**: Define services using a YAML configuration file in your repository

### By code owner{% #by-code-owner %}

Automatically split coverage by code owner teams based on the `CODEOWNERS` file in your repository.

These methods can be used together. Service splitting and code owner splitting work independentlyâyou can have coverage split by both services and code owners simultaneously. For service definitions, Software Catalog integration takes priority over manual configuration. Coverage is calculated for up to 200 services and code owners per coverage report, with a total limit of 2000 services across your organization.

## Software Catalog integration{% #software-catalog-integration %}

If you use [Software Catalog](https://docs.datadoghq.com/service_catalog/), Code Coverage automatically uses the `codeLocations` attribute from your service definitions to calculate coverage for each service.

{% alert level="info" %}
Using Software Catalog for service definitions is the recommended approach, as code locations configured in Software Catalog can be used by multiple Datadog products, including Code Coverage, Error Tracking, and Code Security. Use manual configuration only when Software Catalog integration is not available.
{% /alert %}

### How Software Catalog integration works{% #how-software-catalog-integration-works %}

When you define services in Software Catalog with `codeLocations` pointing to your repository, Code Coverage automatically:

1. Reads the service definitions from Software Catalog
1. Calculates coverage for each service based on the specified paths
1. Displays coverage data in the Code Coverage UI

No additional configuration is needed in your repository.

### Service definition example{% #service-definition-example %}

{% alert level="info" %}
You can add or update service definitions by adding YAML files to your repository, using the Datadog UI, enabling automatic service discovery, or importing from a third-party integration. See the [Software Catalog documentation](https://docs.datadoghq.com/internal_developer_portal/software_catalog/set_up/) for more details.
{% /alert %}

In the `service.datadog.yml` file:

```yaml
apiVersion: v3
kind: service
metadata:
  name: checkout-service
datadog:
  codeLocations:
    - repositoryURL: https://github.com/my-org/my-monorepo.git
      paths:
        - services/checkout/**
        - shared/payment/**
        - shared/cart/**
```

See the [Service Definition documentation](https://docs.datadoghq.com/service_catalog/service_definition_api/) for complete details on the service definition format and available options.

## Code owner-based splitting{% #code-owner-based-splitting %}

Code Coverage can automatically split coverage data based on the `CODEOWNERS` file in your repository. Code owner splitting works independently from service splittingâcoverage can be split by both services and code owners simultaneously.

### How code owner-based splitting works{% #how-code-owner-based-splitting-works %}

When a `CODEOWNERS` file is present, Code Coverage:

1. Reads the code owner assignments from your repository
1. Groups file paths by code owner team
1. Calculates separate coverage metrics for each team's owned code

This happens automatically without requiring any configuration file.

### Requirements for code owner-based splitting{% #requirements-for-code-owner-based-splitting %}

- A `CODEOWNERS` file must exist in your repository (typically at `.github/CODEOWNERS`, `docs/CODEOWNERS`, or `CODEOWNERS` in the root)
- Source code provider integration must be configured (see [Setup](https://docs.datadoghq.com/code_coverage/setup))
- Code owner teams must be properly formatted according to your source code provider's requirements

## Manual service configuration{% #manual-service-configuration %}

{% alert level="info" %}
Manual service configuration should only be used when you cannot use Software Catalog integration. Software Catalog is the preferred method because code locations defined there can be utilized by multiple Datadog products.
{% /alert %}

To manually define services, add a `services` section to the `code-coverage.datadog.yml` file in your repository. See [Configuration](https://docs.datadoghq.com/code_coverage/configuration) for file format details, configuration options, pattern syntax, and examples.

## View coverage data for services and code owners{% #view-coverage-data-for-services-and-code-owners %}

After services or code owners are configured, coverage data becomes available filtered by service or code owner for any coverage reports uploaded after the configuration changes.

On the Branch overview, Pull Request details, and Commit details pages in [Code Coverage UI](https://app.datadoghq.com/ci/code-coverage), use the **Code Owner** or **Service** selector dropdown at the top to:

- View coverage metrics or detailed coverage data filtered to a specific service or code owner
- Identify which files belong to each service or are owned by specific teams
- Compare coverage across different services or code owners
- View coverage trends over time for a specific service or code owner

{% image
   source="https://datadog-docs.imgix.net/images/code_coverage/pr_codeowners.d4df17bdf188687aa38303156ce7b6d8.png?auto=format"
   alt="" /%}

## Set up PR Gates for services and code owners{% #set-up-pr-gates-for-services-and-code-owners %}

You can configure [PR Gates](https://docs.datadoghq.com/pr_gates) to enforce coverage thresholds for specific services or code owners.

### Creating a service or code owner-specific gate{% #creating-a-service-or-code-owner-specific-gate %}

1. Navigate to [PR Gates rule creation](https://app.datadoghq.com/ci/pr-gates/rule/create?dataSource=code_coverage).
1. Configure the coverage threshold (total or patch coverage).
1. In the **per service** or **per code owner** field, select one or more services or code owner teams the gate should apply to.
1. Save the rule.

{% image
   source="https://datadog-docs.imgix.net/images/code_coverage/pr_gate_codeowners.43bb8a3c883058e65136ca940bd22666.png?auto=format"
   alt="" /%}

### How service and code owner gates work{% #how-service-and-code-owner-gates-work %}

- **With services or code owners specified**: The gate evaluates coverage separately for each selected service or code owner team. When multiple services or code owners are specified, each is evaluated independently against the threshold. The gate does not combine coverage across services or code owners.
- **Without services or code owners specified**: The gate evaluates coverage for the entire repository.

### Example configurations{% #example-configurations %}

**Enforce high coverage for backend services:**

- Condition type: `Overall Code Coverage`
- Threshold: `80%`
- Scope: `Per service`
- Services: `backend-*`

{% image
   source="https://datadog-docs.imgix.net/images/code_coverage/pr_gate_backend_services.3ca10196dd183bb4e089959e125a9973.png?auto=format"
   alt="" /%}

**Require all new code in frontend to be tested:**

- Condition type: `Patch Code Coverage`
- Threshold: `100%`
- Scope: `Per service`
- Services: `admin-dashboard`, `frontend-*`

{% image
   source="https://datadog-docs.imgix.net/images/code_coverage/pr_gate_frontend.6864718e70ddb4c42544ebd745f716b2.png?auto=format"
   alt="" /%}

**Enforce coverage for specific team's code:**

- Condition type: `Patch Code Coverage`
- Threshold: `90%`
- Scope: `Per code owner`
- Code owners: `@team/platform`

{% image
   source="https://datadog-docs.imgix.net/images/code_coverage/pr_gate_codeowners_team.f0e1c977d0da08ae07e91117764c6790.png?auto=format"
   alt="" /%}

### Multiple gates per repository{% #multiple-gates-per-repository %}

You can create multiple gates for the same repository, each applying to different services or code owners. This allows you to enforce different coverage standards for different parts of your monorepo or for different teams.

## Troubleshooting{% #troubleshooting %}

### Software Catalog services are not appearing in the UI{% #software-catalog-services-are-not-appearing-in-the-ui %}

When using Software Catalog integration, changes to service definitions in Software Catalog may take up to 10 minutes to synchronize with Code Coverage. After creating or updating service definitions in Software Catalog:

1. Verify that the service definition in Software Catalog includes `codeLocations` with the correct `repositoryURL`.
1. Ensure the paths specified in `codeLocations` match the actual file structure.
1. Wait up to 10 minutes for the changes to propagate.
1. Upload a new coverage report after the synchronization completes.

Software Catalog is queried when processing coverage reports, so changes only take effect for newly uploaded reports.

### Manual service configuration not taking effect{% #manual-service-configuration-not-taking-effect %}

If manually configured services don't appear in the UI:

1. Ensure the `code-coverage.datadog.yml` file is at the repository root.
1. Validate the YAML syntax (use a YAML validator to check for errors).
1. Verify that source code provider integration is properly configured (see [Setup](https://docs.datadoghq.com/code_coverage/setup)).
1. Upload a new coverage report after adding or modifying the configuration file.

The configuration file is read when processing coverage reports, so changes only take effect for newly uploaded reports.

### Coverage values don't match expected service or code owner boundaries{% #coverage-values-dont-match-expected-service-or-code-owner-boundaries %}

Check that:

1. Path patterns in your configuration correctly match the intended files
1. Paths in coverage reports are relative to the repository root (as expected by Code Coverage)

If paths in coverage reports are relative to a subdirectory, use the `--base-path` option when uploading:

```shell
datadog-ci coverage upload --base-path=src .
```



### Coverage not calculated for some services or code owners{% #coverage-not-calculated-for-some-services-or-code-owners %}

Code Coverage has the following limits:

- **Per-report limit (200)**: Up to 200 services and code owners combined per coverage report
- **Organization-wide service limit (2000)**: Up to 2000 services total across all repositories in your organization

If you exceed these limits, coverage is not calculated for services or code owners beyond the limit.

To stay within limits:

1. Consolidate related services into broader categories.
1. Remove unused or redundant service definitions.

### Code owner-based coverage not appearing{% #code-owner-based-coverage-not-appearing %}

Confirm that:

1. A `CODEOWNERS` file exists in the standard location (`.github/CODEOWNERS`, `docs/CODEOWNERS`, or `CODEOWNERS` in the root)
1. Source code provider integration has access to read the file (see [Setup](https://docs.datadoghq.com/code_coverage/setup))
1. The code owner format follows your provider's syntax requirements
1. At least one coverage report has been uploaded after the `CODEOWNERS` file was added or updated

## Further reading{% #further-reading %}

- [Set up Code Coverage](https://docs.datadoghq.com/code_coverage/setup)
- [Datadog Software Catalog](https://www.datadoghq.com/product/software-catalog/)