Codecov Coverage Report Cache Invalidation Policy

Answer to the three questions

Does Codecov invalidate a cached report when the coverage file changes but the commit hash stays the same?

Confirmed: Codecov identifies a report by repository owner/name, provider commit SHA, and optionally PR number and flags. Badge and dashboard URLs are parameterized by those identifiers. The key is commit-based, not time-based.

Likely: Re-uploading coverage for an existing commit SHA updates the stored report timestamp and the coverage shown for that SHA, effectively replacing the previous payload for that key. Exact overwrite versus merge behavior can depend on uploader configuration and flags. A force-push that truly keeps the same SHA cannot change file content without changing the SHA, so the scenario of "same SHA, different coverage" is not a normal Git workflow.

Is there a documented time-based expiration policy for cached reports?

Confirmed: No documented time-based expiration policy for stored coverage reports is published. Reports are retained per commit/PR key.

Likely: Badge and dashboard responses are served via CDN. Apparent staleness is typically CDN propagation latency, not a policy TTL. Short lag after a successful upload is expected.

How is cache handled when a PR is merged or rebased onto a new commit?

Confirmed: A new commit SHA creates a new report entry. Merging or rebasing a PR normally produces new SHAs on base and head, so a fresh report is required for the new SHA. The old SHA report remains unchanged.

Likely: If the CI uploads only for the old SHA after a rebase, the UI will continue to show the old report for that SHA. The new SHA will appear empty until a coverage upload is made for it.

Confirmed facts vs likely explanation

Confirmed

• Report identity is repository + commit SHA + optional PR number + flags.
• New SHA = new report entry.
• No public time-based expiration for stored reports.

Likely

• Re-upload to same SHA updates the report for that SHA.
• Badge lag is CDN caching, not report retention.
• Stale badges after force-push/rebase are usually missing upload for the new SHA or CDN latency, not cache retention for an unchanged SHA.

Steps to ensure fresh badge/dashboard data for this case

1. Verify the SHA used in CI matches the SHA shown in Codecov UI for the commit/PR. After rebase/merge, ensure CI runs on the new SHA.
2. Confirm upload success in CI logs and compare the upload timestamp and report_id with the "Last updated" timestamp in Codecov UI for that commit.
3. If you must re-upload to an existing SHA, trigger a new upload and wait 5-15 minutes for CDN propagation before concluding staleness.
4. Inspect network response headers for the badge SVG URL to see Cache-Control max-age and confirm CDN caching duration.

One diagnostic detail that changes the recommendation: which flags and uploader configuration are used in the upload. Upload deduplication and flags can cause reports to be merged rather than replaced for the same SHA, leading to unexpected values.