How to Ditch Codecov for Python Projects
Codecov’s unreliability breaking CI on my open source projects has been a constant source of frustration for me for years. I have found a way to enforce coverage over a whole GitHub Actions build matrix that doesn’t rely on third-party services.<br>Coverage.py has the option to fail the call to coverage report if coverage is less than XXX already built in: either the setting fail_under=XXX or the command line option --fail-under=XXX. The only reason why I’ve traditionally used Codecov (including in my Python in GitHub Actions guide), is because I need to measure coverage over multiple Python versions that run in different containers. Therefore I can’t just run coverage combine, I need to store them somewhere between the various build matrix items.<br>Unfortunately, Codecov has grown very flaky. I have lost any confidence in the fact when it fails a build and my first reaction is always to restart the build and only then investigate. Sometimes the upload fails, sometimes Codecov fails to report its status back to GitHub, sometimes it can’t find the build, and sometimes it reports an outdated status. What a waste of computing power. What a waste of my time, clicking through their web application, seeing everything green, yet the build is failing due to missing coverage.<br>When I complained about this once again and even sketched out my idea how it could work, I’ve been told that the cookiecutter-hypermodern-python project has already been doing it1 and there’s a GitHub Action taking the same approach!<br>So, I removed Codecov from all my projects and it’s glorious! Not only did I get rid of a flaky dependency, it also simplified my workflow. The interesting parts are the following:<br>After running the tests under coverage in parallel mode, add a step that uploads the coverage files as artifacts as part of the test-running jobs:<br>- name: Upload coverage data<br>uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1<br>with:<br>name: coverage-data-${{ matrix.python-version }}<br>path: .coverage.*<br>include-hidden-files: true<br>if-no-files-found: ignore
You need this for every item in your build matrix whose coverage you want to take into account. You have to add every dimension of your matrix to the name. This example assumes that your matrix only consists of Python versions, which is true for most Python projects.<br>I use if-no-files-found: ignore, because I don’t run all Python versions under coverage. It’s much slower and I don’t need every Python version to ensure 100% coverage.<br>After all tests passed , add a new job:<br>coverage:<br>name: Ensure 100% test coverage<br>runs-on: ubuntu-latest<br>needs: tests<br>if: always()
steps:<br>- uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3<br>with:<br>persist-credentials: false<br>- uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0<br>with:<br># latest version you support, so it understands all syntax<br>python-version: "3.14"<br>- uses: hynek/setup-cached-uv@4300ec2180bc77d705e626a34e381b81a4772c51 # v2.5.0
- name: Download coverage data<br>uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1<br>with:<br>pattern: coverage-data-*<br>merge-multiple: true
- name: Combine coverage and fail if it's<br>run: |<br>uv tool install coverage
coverage combine<br>coverage html --skip-covered --skip-empty
# Report and write to summary.<br>coverage report --format=markdown >> $GITHUB_STEP_SUMMARY
# Report again and fail if under 100%.<br>coverage report --fail-under=100
- name: Upload HTML report if check failed<br>uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1<br>with:<br>name: html-report<br>path: htmlcov<br>if: ${{ failure() }}
It sets needs: tests to ensure all tests are done, but it also sets if: always() such that the coverage is measured even if one of the tests jobs fails. If your job that runs tests has a different name, you will have to adapt this. Check out the full workflow if you’re unsure where exactly to put the snippets.<br>In a nutshell:<br>It downloads the coverage data that the tests uploaded as artifacts,<br>combines it,<br>creates an HTML report,<br>creates a Markdown report that is added to the job summary,<br>and finally checks if coverage is 100% – failing the job if it is not. If – and only if! – this step fails (presumably due to a lack of coverage), it also uploads the HTML report as an artifact.<br>Once the workflow is done, you can see the plain-text report at the bottom of the workflow summary page. If the coverage check failed, there’s also the HTML version for download.<br>The workflow summary with a plain-text report.
If you’d like a coverage badge, check out Ned’s guide: Making a coverage badge.<br>Note on uv<br>This workflow uses uv to install and invoke Coverage.py, because it’s fast and amazing. The rest of your project doesn’t have to use uv.<br>It also uses my own setup-cached-uv, but feel free to...