Make Patch Coverage a Blocking Pull Request Gate with Codecov Flags

Block new code from merging without coverage

Project-wide coverage targets rarely stop a pull request that adds untested logic, because the new lines are a small fraction of the repository. Codecov's patch status check solves this by evaluating only the lines changed in the pull request. To make it a hard gate, define per-suite flags and a patch target in codecov.yml, upload each test suite with its matching flag, then mark the resulting status check as required in your Git provider's branch protection. This assumes your repository has a Git provider integration and that your test runner emits a supported coverage report format.

How Codecov decides what to check

Codecov keys every upload by commit SHA and merges all reports received for that commit. Flags do not change how reports are merged; they partition the merged file list by path patterns, so backend and frontend coverage remain separate. The patch status compares the diff of the pull request against the base commit and calculates coverage only for added or modified lines. The project status, by contrast, evaluates the entire tree. A repository can pass a project target while a patch target fails, which is exactly the gap this gate closes.

Worked configuration

Place this at the repository root or in the path your integration expects. The example assumes two test suites with separate coverage outputs.

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

flags:
  backend:
    paths:
      - services/api/**
  frontend:
    paths:
      - apps/web/**

The patch.default block applies to every flag unless a flag-specific patch block overrides it. target: auto tells Codecov to choose a target based on the base commit's coverage, so the bar moves with the repository rather than staying fixed. The threshold allows a small margin below the target before failing. Setting informational: false makes the check eligible to block merges.

Uploading each suite with its flag

Run the uploader from your CI workspace after each test job completes. The repository uploader reads the token from the environment; never hard-code it in the YAML or the build log.

# Run in the CI job that executes the backend tests
codecov -t "$CODECOV_TOKEN" -F backend -f services/api/coverage.xml

Run the equivalent command for the frontend suite, changing the flag and file path. The -F value must match the flag name in codecov.yml exactly. If the uploader runs from a directory that does not match the repository-relative paths in your coverage report, files will land under the wrong flag or be ignored; add path fixing in that case.

Turning the check into a required gate

After the first upload, Codecov posts a status check to the pull request. In your Git provider's branch protection or ruleset settings, add the Codecov patch check to the list of required status checks. Until that step is done, the check is advisory only. If you set informational: true, the check stays green for reporting purposes but never blocks.

Limits to plan around

• Patch coverage ignores unchanged lines. A large, well-tested file can still fail if the new lines lack tests, and a tiny diff can pass with one covered line.
• target: auto needs a comparable base commit. Force-pushes, rebases, or detached SHAs can leave the check pending or unable to resolve a base.
• Flags only work when uploads match. If a job forgets -F backend, its files may fall into the default flag or be double-counted.
• CI checkout paths may differ. Monorepo checkouts or sparse checkouts often need path fixing so that services/api/** matches the actual report paths.
• Status checks depend on the integration. The commit SHA in CI must match the SHA the provider reports, or the check will not attach to the pull request.

Common mistakes

• Committing tokens. Codecov suffered a 2021 uploader supply-chain breach; treat tokens as sensitive, rotate them, and pin or verify the uploader you execute.
• Reusing one flag for unrelated suites. Backend and frontend coverage merged under one flag makes the per-suite numbers meaningless and can double-count files.
• Leaving informational: true. The check looks present but does not block.
• Forgetting branch protection. A red check in the pull request view does not stop a merge unless it is marked required.
• Relying on an old uploader. After credential rotation or uploader changes, legacy commands may fail silently or drop reports.

Verifying the gate before you rely on it

1. Open a pull request that changes one covered line and one uncovered line. Confirm the Codecov patch check is red below target and turns green after you add a test or lower the threshold.
2. In Codecov's commit view, check that each upload appears under the expected flag and that files map to the correct paths. If not, add path fixing and re-run.
3. Temporarily set informational: true, confirm the check is non-blocking, then set it to false and mark it required in branch protection.
4. Run the uploader from a different working directory or checkout path to confirm path fixing before enforcing the gate on the whole team.

Because YAML keys, uploader flags, and tokenless/OIDC support are version- and plan-sensitive, confirm the exact syntax against current Codecov documentation before rolling this out broadly.