Add YAML-based PR Gates to Code Coverage docs

content/en/code_coverage/configuration.md

@@ -33,6 +33,13 @@ services:
 ignore:
   - "test/**/*"
   - "**/*.pb.go"
+gates:
+  - type: total_coverage_percentage
+    config:
+      threshold: 85
+  - type: patch_coverage_percentage
+    config:
+      threshold: 95
 ```
 
 ## Services configuration
@@ -154,6 +161,112 @@ ignore:
 ```
 {{% /collapse-content %}}
 
+## PR Gates
+
+You can define [PR Gates][2] in the configuration file to enforce code coverage thresholds on pull requests. If gates are also configured in the [Datadog UI][2], Datadog evaluates both the configuration file rules and the UI rules when a PR is opened or updated.
+
+<div class="alert alert-info">If both the configuration file and the Datadog UI define gates for the same scope, the pull request must meet every defined threshold.</div>
+
+```yaml
+gates:
+  - type: total_coverage_percentage
+    config:
+      threshold: 85
+
+  - type: patch_coverage_percentage
+    config:
+      threshold: 95
+```
+
+Each gate has the following fields:
+
+- `type` (required): The type of coverage gate. Supported values:
+  - `total_coverage_percentage`: The minimum overall coverage percentage for the repository (or for the scoped services or code owners).
+  - `patch_coverage_percentage`: The minimum coverage percentage on code changed in the pull request.
+- `config` (required): Gate configuration options. Supported values:
+  - `threshold` (required): The minimum coverage percentage (0-100).
+  - `services`: (optional) A list of service name patterns to scope the gate to. Use `*` as a wildcard. When set, coverage is evaluated separately for each matching service.
+  - `codeowners`: (optional) A list of code owner patterns to scope the gate to. Use `*` as a wildcard. When set, coverage is evaluated separately for each matching code owner.
+  - `flags`: (optional) A list of [flag][3] name patterns to scope the gate to. Use `*` as a wildcard. When set, coverage is evaluated separately for each matching flag.
+
+### Examples
+
+{{% collapse-content title="Unscoped total and patch coverage gates" level="h4" %}}
+{{< code-block lang="yaml" filename="code-coverage.datadog.yml" >}}
+schema-version: v1
+gates:
+  - type: total_coverage_percentage
+    config:
+      threshold: 80
+
+  - type: patch_coverage_percentage
+    config:
+      threshold: 90
+{{< /code-block >}}
+{{% /collapse-content %}}
+
+{{% collapse-content title="Gates scoped to services" level="h4" %}}
+{{< code-block lang="yaml" filename="code-coverage.datadog.yml" >}}
+schema-version: v1
+services:
+  - id: backend-api
+    paths:
+      - backend/api/**
+  - id: frontend-web
+    paths:
+      - frontend/**
+gates:
+  - type: patch_coverage_percentage
+    config:
+      threshold: 90
+      services:
+        - "*"
+
+  - type: total_coverage_percentage
+    config:
+      threshold: 85
+      services:
+        - "backend-api"
+{{< /code-block >}}
+{{% /collapse-content %}}
+
+{{% collapse-content title="Gates scoped to code owners" level="h4" %}}
+{{< code-block lang="yaml" filename="code-coverage.datadog.yml" >}}
+schema-version: v1
+gates:
+  - type: patch_coverage_percentage
+    config:
+      threshold: 95
+      codeowners:
+        - "@DataDog/backend-team"
+        - "@DataDog/api-*"
+
+  - type: total_coverage_percentage
+    config:
+      threshold: 80
+      codeowners:
+        - "@DataDog/frontend-team"
+{{< /code-block >}}
+{{% /collapse-content %}}
+
+{{% collapse-content title="Gates scoped to flags" level="h4" %}}
+{{< code-block lang="yaml" filename="code-coverage.datadog.yml" >}}
+schema-version: v1
+gates:
+  - type: total_coverage_percentage
+    config:
+      threshold: 80
+      flags:
+        - "unit-tests"
+
+  - type: patch_coverage_percentage
+    config:
+      threshold: 90
+      flags:
+        - "integration-tests"
+{{< /code-block >}}
+{{% /collapse-content %}}
+
 ## Pattern syntax
 
 Configuration options that accept file paths support three types of patterns:
@@ -197,3 +310,5 @@ Simple path prefixes without special characters are treated as prefix matches:
 {{< partial name="whats-next/whats-next.html" >}}
 
 [1]: /code_coverage/monorepo_support
+[2]: https://app.datadoghq.com/ci/pr-gates/rule/create?dataSource=code_coverage
+[3]: /code_coverage/flags

content/en/code_coverage/flags.md

@@ -95,7 +95,14 @@ When you select a flag, the coverage metrics update to show only the data from r
 
 You can configure [PR Gates][1] to enforce coverage thresholds for specific flags. This allows you to enforce different coverage requirements for different test types or runtime versions.
 
-### Create a flag-specific gate
+You can create flag-specific gates in one of two ways:
+
+- **Datadog UI**: Navigate to [PR Gates rule creation][2] and configure a rule with per-flag scope.
+- **YAML configuration file**: Define gates with the `flags` field in your [`code-coverage.datadog.yml`][5] file. This allows you to manage gates as code alongside your repository.
+
+Rules from both sources are evaluated when a pull request is opened or updated. See [Configuration][5] for YAML gate syntax and examples.
+
+### Create a flag-specific gate in the Datadog UI
 
 1. Navigate to [PR Gates rule creation][2].
 2. Configure the coverage threshold (total or patch coverage).
@@ -167,3 +174,4 @@ datadog-ci coverage upload --flags python-3.12 coverage-py312.xml
 [2]: https://app.datadoghq.com/ci/pr-gates/rule/create?dataSource=code_coverage
 [3]: /code_coverage/monorepo_support
 [4]: https://app.datadoghq.com/ci/code-coverage
+[5]: /code_coverage/configuration#pr-gates

content/en/code_coverage/monorepo_support.md

@@ -111,7 +111,7 @@ On the Branch overview, Pull Request details, and Commit details pages in [Code
 
 You can configure [PR Gates][7] to enforce coverage thresholds for specific services or code owners.
 
-### Creating a service or code owner-specific gate
+### Using the Datadog UI
 
 1. Navigate to [PR Gates rule creation][3].
 2. Configure the coverage threshold (total or patch coverage).
@@ -120,6 +120,29 @@ You can configure [PR Gates][7] to enforce coverage thresholds for specific serv
 
 {{< img src="/code_coverage/pr_gate_codeowners.png" text="Code Coverage PR gate creation page in Datadog" style="width:100%" >}}
 
+### Using the YAML configuration file
+
+You can also define service- or code owner-scoped gates directly in your [`code-coverage.datadog.yml`][8] file using the `services` and `codeowners` fields:
+
+{{< code-block lang="yaml" filename="code-coverage.datadog.yml" >}}
+schema-version: v1
+gates:
+  - type: patch_coverage_percentage
+    config:
+      threshold: 90
+      services:
+        - "*"
+
+  - type: patch_coverage_percentage
+    config:
+      threshold: 95
+      codeowners:
+        - "@DataDog/backend-team"
+        - "@DataDog/api-*"
+{{< /code-block >}}
+
+Gates defined in the YAML file and in the Datadog UI are both evaluated when a pull request is opened or updated. See [PR Gates configuration instructions][8] for the complete YAML syntax and additional examples.
+
 ### 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.
@@ -225,3 +248,4 @@ Confirm that:
 [5]: https://app.datadoghq.com/ci/code-coverage
 [6]: /code_coverage/configuration
 [7]: https://app.datadoghq.com/ci/pr-gates/rule/create?dataSource=code_coverage
+[8]: /code_coverage/configuration#pr-gates

content/en/code_coverage/setup.md

@@ -90,9 +90,12 @@ Navigate to [Roles settings][4], click `Edit` on the role you need, add the `Cod
 
 ## PR Gates
 
-If you wish to gate on PR coverage, configure PR Gates rules in Datadog.
+If you wish to gate on PR coverage, you can configure PR Gates rules in one of two ways:
 
-Navigate to [PR Gates rule creation][5] and configure a rule to gate on total or patch coverage.
+- **Datadog UI**: Navigate to [PR Gates rule creation][5] and configure a rule to gate on total or patch coverage.
+- **YAML configuration file**: Define gates in your [`code-coverage.datadog.yml`][14] file. This allows you to manage gates as code alongside your repository.
+
+Rules from both sources are evaluated when a pull request is opened or updated. See [Configuration][14] for YAML gate syntax and examples.
 
 ## Upload code coverage reports
 
@@ -468,7 +471,7 @@ Datadog deduplicates overlapping files across reports, which can result in diffe
 [2]: /account_management/rbac/permissions/#custom-roles
 [3]: /account_management/rbac/permissions/#managed-roles
 [4]: https://app.datadoghq.com/organization-settings/roles
-[5]: https://app.datadoghq.com/ci/pr-gates/rule/create
+[5]: https://app.datadoghq.com/ci/pr-gates/rule/create?dataSource=code_coverage
 [6]: /code_coverage/data_collected/#code-coverage-report-upload
 [7]: https://www.npmjs.com/package/@datadog/datadog-ci
 [8]: https://github.com/DataDog/datadog-ci/releases
@@ -477,3 +480,4 @@ Datadog deduplicates overlapping files across reports, which can result in diffe
 [11]: https://app.datadoghq.com/ci/code-coverage
 [12]: #integrate-with-source-code-provider
 [13]: https://hub.docker.com/r/datadog/ci
+[14]: /code_coverage/configuration#pr-gates