Using Codecov Diff Coverage to Guard New Code in Pull Requests

The Problem with Total Coverage in PRs

When a pull request triggers a coverage report, the most visible number is the Total Coverage percentage. In a large repository this figure can change only slightly even when the new code introduces many untested lines, making it hard for reviewers to spot risky changes.

How Diff Coverage Is Calculated

Diff coverage (also called patch coverage) looks only at the lines that were added, modified, or deleted in the current commit. Codecov compares the coverage data of the commit with the baseline of the target branch and reports the percentage of those changed lines that were executed by tests.

Setting a Patch Threshold in .codecov.yml

To turn diff coverage into a blocking gate you define a patch threshold. The configuration lives in the repository root and is read by the Codecov backend after your CI uploads the coverage report.

# .codecov.yml
coverage:
  status:
    project:
      default:
        target: auto   # keep overall coverage roughly where it is
        threshold: 2%  # allow a small dip in total coverage
    patch:
      default:
        target: 80%    # new code must reach at least 80% coverage
        threshold: 0%  # no tolerance below the target

Where to apply: Commit this file to the default branch; any subsequent PR will be evaluated against it.

Permissions needed: Write access to the repository to add or modify .codecov.yml.

What to look for: After pushing a PR, open the GitHub Checks tab. If the reported patch coverage is below 80% the check will show as failed and the PR cannot be merged.

Worked Example: Enforcing 80% Diff Coverage

Suppose a developer adds a new utility file with 20 lines of code. The test suite executes 15 of those lines.

1. The CI runs tests and generates coverage.xml.
2. The CI uploads the report to Codecov.
3. Codecov computes diff coverage: 15 / 20 = 75%.
4. Because the patch target is 80% and the threshold is 0%, the check fails.
5. The developer adds a test for the missing five lines, pushes again, and the diff coverage rises to 80% or higher, allowing the PR to pass.

Trade-off: Missing Regressions in Untouched Files

Diff coverage protects against untested new code but does not exercise existing files. A change in File A could cause a test in File B to start failing, lowering overall coverage without affecting the diff metric. To catch such indirect regressions keep a loose project threshold (as shown above) or schedule a weekly total‑coverage audit.

Verifying the Numbers

You can confirm that the PR comment matches the underlying data.

1. On the GitHub PR page, open the Checks tab and note the Patch percentage displayed by Codecov.
2. Locally, run the Codecov CLI against the same coverage file: codecov -f coverage.xml --flags=pr. The output includes a line like Patch coverage: 75%.
3. If the two numbers differ, check that the CI uploaded the correct coverage file and that the baseline branch matches the PR's target.

Actionable Closing

Replace a reliance on total coverage with a diff-coverage gate. By adding a patch target to .codecov.yml you ensure every new line of code is tested, while still monitoring overall health with a permissive project threshold. This approach reduces reviewer fatigue and keeps the focus on the code that actually changed.