Enforce Diff Coverage on Pull Requests with Codecov Patch Status Checks

The Problem: Uploaded Coverage That Never Blocks a Merge

Coverage reports often appear in pull request comments without changing merge behavior. A reviewer sees that diff coverage dropped, but nothing stops the merge because no status check is configured to fail. The fix is to add a patch coverage status check to your Codecov configuration so the pull request itself reports failure when changed lines are not adequately tested.

Desired Outcome

A required status check—commonly named codecov/patch or a provider-specific variant—that evaluates only the lines changed in a pull request. When those lines fall below a minimum coverage threshold, the check fails and the pull request cannot be merged until tests are added or the threshold is adjusted. This is distinct from project coverage, which measures the entire repository.

Prerequisites

• A repository already connected to Codecov.
• A CI pipeline that generates coverage reports and uploads them using the currently recommended uploader for your language.
• A codecov.yml or .codecov.yml file committed to the repository root.
• Write access to repository settings so you can configure branch protection rules.

Procedure

1. Add the patch status block

In the repository root, create or edit codecov.yml. Add a coverage.status.patch section. The following is a representative structure; verify exact keys against current Codecov documentation because the schema varies by plan and CI provider.

coverage:
  status:
    patch:
      default:
        target: auto
        threshold: 0%
        informational: false

Key fields to review:

• target: auto compares the pull request against the base branch's coverage. A percentage such as 80% sets an absolute floor.
• threshold: The tolerated drop below the target before the check fails. 0% means any drop triggers failure.
• informational: When false, the check can block merges. When true, it is advisory only.

Save the file in the repository root. No elevated permissions are needed beyond normal write access to the repository.

2. Commit and push to trigger evaluation

Commit the configuration to your default branch using standard Git commands, then open or update a pull request. The next CI run should invoke the Codecov uploader and evaluate the patch status.

git add codecov.yml
git commit -m "Add patch coverage status check"
git push origin <branch-name>

Replace <branch-name> with your feature branch. The risk here is limited: a syntax error in YAML can cause the status check to be skipped rather than fail, so validate the file before relying on it.

3. Require the status check in branch protection

On GitHub, navigate to Settings → Branches → Branch protection rules → Require status checks, and add the exact check name reported by Codecov (for example, codecov/patch). On GitLab, configure the equivalent pipeline gate. Without this step, the check may run but will not prevent merging.

Expected Checks

• The pull request displays a Codecov status check that reports pass or fail based on diff coverage.
• CI job logs show successful report ingestion and a status check URL.
• The Codecov UI shows a patch diff highlighting covered and uncovered changed lines.
• When changed lines meet the threshold, the check passes; when they do not, it fails.

Recovery Options

If the status check is absent

• Verify the upload token or confirm the repository is public if no token is used.
• Check that coverage report file paths match what the uploader expects.
• Confirm CI environment variables such as commit SHA and pull request number are correctly exported.

If failures are unexpected

• Inspect the patch diff in the Codecov UI to identify which changed lines are uncovered.
• Adjust threshold or target if the initial configuration is too strict for legacy code.
• Use ignore or path filters to exclude generated files or vendored code from the patch calculation.

Limitations

• Patch coverage applies only to changed lines, not the full project. Do not confuse it with project coverage targets.
• The codecov.yml schema and status check names vary by CI provider and Codecov plan. Verify exact keys against current documentation.
• Uploader behavior has changed over time, including the deprecation of the bash uploader. Use the currently recommended uploader for your language and CI.

Practical Verification

1. Open a test pull request that adds uncovered lines. Confirm the Codecov status check fails.
2. Add tests that cover those lines. Confirm the check passes.
3. Validate the YAML syntax using the Codecov web UI validator or the CLI validation command (verify the exact command syntax in current documentation).