Skip to content
coverctl

Policy basics

.coverctl.yaml is what your AI coding agent reads when it calls coverctl check. It defines which directories belong to which domain (auth, payments, utilities, …) and what coverage threshold each domain must meet. The agent reads the same file you do — there is no separate agent-mode configuration.

This page is the file-format reference. For deeper patterns — diff-based enforcement, profile merging, integration tests — see Advanced configuration.

File Location

Section titled “File Location”

By default, coverctl looks for .coverctl.yaml in the current directory. If not found, it searches parent directories automatically (useful for monorepos).

Terminal window
# Use custom config path
coverctl check -c config/coverage.yaml


# Auto-detects from current or parent directories
cd packages/mypackage && coverctl check

Supported file names

Section titled “Supported file names”

coverctl searches for these files in order:

  1. .coverctl.yaml
  2. .coverctl.yml
  3. coverctl.yaml
  4. coverctl.yml

Basic Structure

Section titled “Basic Structure”
version: 1


policy:
  default:
    min: 75
  domains:
    - name: core
      match: ["./internal/core/..."]
      min: 85


exclude:
  - "**/generated/**"

Configuration Options

Section titled “Configuration Options”

version

Section titled “version”

Required. Schema version for future compatibility.

version: 1

extends

Section titled “extends”

Inherit configuration from a parent file. Useful for monorepos where packages share common policies.

packages/api/.coverctl.yaml
extends: ../../.coverctl.yaml  # Path relative to this config file


policy:
  domains:
    - name: api
      match: ["./..."]
      min: 90  # Override parent threshold

Child configs override parent values. See Monorepo Support for details.

policy

Section titled “policy”

Coverage policy configuration. See Policies.

policy:
  default:
    min: 75
  domains:
    - name: core
      match: ["./internal/core/..."]
      min: 85

exclude

Section titled “exclude”

Glob patterns for files to exclude from coverage. See Domains.

exclude:
  - "**/generated/**"
  - "**/mocks/**"
  - "**/*_test.go"

files

Section titled “files”

Per-file coverage rules. See Policies.

files:
  - match: ["internal/core/*.go"]
    min: 90

diff

Section titled “diff”

Diff-based coverage mode. See Advanced.

diff:
  enabled: true
  base: origin/main

integration

Section titled “integration”

Integration test coverage. See Advanced.

integration:
  enabled: true
  packages: ["./internal/integration/..."]
  run_args: ["-test.run", "TestIntegration"]

merge

Section titled “merge”

Profile merging. See Advanced.

merge:
  profiles:
    - ".cover/unit.out"
    - ".cover/integration.out"

annotations

Section titled “annotations”

Code annotation support. See Advanced.

annotations:
  enabled: true

Complete Example

Section titled “Complete Example”
version: 1


policy:
  default:
    min: 75
  domains:
    - name: core
      match: ["./internal/core/..."]
      min: 85
    - name: api
      match: ["./internal/api/..."]
      min: 80
    - name: infrastructure
      match: ["./internal/infrastructure/..."]
      min: 70
    - name: cli
      match: ["./cmd/..."]
      min: 75


files:
  - match: ["internal/core/critical/*.go"]
    min: 95


exclude:
  - "**/generated/**"
  - "**/mocks/**"
  - "**/testdata/**"


diff:
  enabled: false
  base: origin/main


integration:
  enabled: false
  packages: ["./internal/integration/..."]
  run_args: []
  cover_dir: ".cover/integration"
  profile: ".cover/integration.out"


merge:
  profiles: []


annotations:
  enabled: true

Schema Validation

Section titled “Schema Validation”

A JSON schema is available at schemas/coverctl.schema.json for editor integration:

# yaml-language-server: $schema=./schemas/coverctl.schema.json
version: 1
...

Next Steps

Section titled “Next Steps”