Direct Answer
Based on current Codecov SaaS behavior:
- Omitted flags are not treated as zero coverage. They are excluded from the overall percentage calculation for that build.
- The denominator includes only flags present in the upload. Flags defined in
codecov.yml but absent from a given coverage report do not participate in the aggregation.
- No tier difference for core aggregation. Free and paid tiers use the same denominator rule; paid tiers add flag-management UI and custom status checks but do not alter the overall-coverage calculation.
How the Aggregation Works
Codecov computes overall project coverage per commit by averaging the coverage percentages of only the flags that appear in that upload. Each flag contributes its own line/branch coverage ratio; the overall value is the mean of those ratios. If codecov.yml defines unit and integration flags but a CI job uploads only unit, the overall coverage for that build equals the unit flag's coverage alone. The integration flag is simply absent—it adds neither numerator nor denominator.
Prior values are not carried forward. A flag that was uploaded in the previous build but omitted in the current one disappears from the current build's overall figure. This causes the overall percentage to fluctuate when flag sets vary across matrix jobs or conditional uploads.
Verification Steps
You can confirm this behavior in your own repository:
- Create a test repo with a
codecov.yml defining two flags e.g. unit, integration and a global threshold.
- Push a commit that uploads coverage for only the
unit flag using -F unit on the uploader. Note the overall coverage shown on the Codecov commit page.
- Push a second commit uploading both flags. Compare the overall coverage; it should reflect the average of both flags, not a zero-weighted average.
- Optionally query the Codecov API:
GET https://api.codecov.io/api/v2/gh/:owner/:repo/commit/:sha. The flags object lists only uploaded flags and the top-level coverage field matches their aggregate.
Assumptions and Uncertainties
- Observations apply to Codecov SaaS as of late 2024; SaaS behavior can change without versioned release notes.
- Self-hosted Codecov Enterprise may implement different flag-aggregation logic depending on version and configuration.
- Merged reports from multiple uploads in the same commit can make a flag appear present even if a single job omits it.
- Carrier flags and custom status-check configurations may introduce edge cases not covered by the core rule.
One Diagnostic Detail That Changes the Recommendation
If you are using Codecov Enterprise self-hosted rather than SaaS, the aggregation logic may differ. Confirm which deployment you are on; if Enterprise, share the version string from your instance's admin panel.
codecov