Upload Code Coverage to Codecov from CircleCI (2026)

Codecov is a service that analyzes your code coverage reports and provides insights into your test coverage. CircleCI is a popular CI/CD platform that automates your build, test, and deployment pipelines. Integrating Codecov with CircleCI allows you to automatically upload your code coverage reports after each build, giving you up-to-date visibility into your test coverage.

Here’s how to set up the integration:

1. Get Your Codecov Token

First, you’ll need a Codecov token.

• Go to codecov.io and log in.
• Navigate to your repository’s settings page.
• Under the "General" tab, you’ll find your "API Token". Copy this token.

2. Add the Token to CircleCI Environment Variables

It’s crucial to keep your token secure. The best way to do this is by storing it as an environment variable in CircleCI.

• Go to your project in CircleCI.
• Click on "Project Settings".
• Select "Environment Variables" from the sidebar.
• Click "Add Variable".
• For the "Name", enter CODECOV_TOKEN.
• For the "Value", paste the API token you copied from Codecov.
• Click "Add Variable".

3. Configure Your config.yml

Now, you need to tell CircleCI to upload your coverage reports to Codecov. You’ll do this by adding a step to your CI job. The exact placement depends on your workflow, but it typically goes after your tests have run.

Here’s an example of how to add this to your .circleci/config.yml:

version: 2.1

jobs:
  build-and-test:
    docker:
      - image: cimg/node:18.17.1 # Example Docker image, use one appropriate for your project
    steps:
      - checkout
      # Install dependencies, run tests, etc.
      - run: npm install
      - run: npm test -- --coverage # Assuming your tests generate coverage reports

      # Upload coverage to Codecov
      - run: bash <(curl -s https://codecov.io/env)
      - run: bash <(curl -s https://codecov.io/bash)

workflows:
  version: 2
  build:
    jobs:
      - build-and-test

Let’s break down the Codecov steps:

• bash <(curl -s https://codecov.io/env): This command fetches environment variables that Codecov can use to better understand your CI environment. It’s not strictly required for basic uploads but can help Codecov provide more detailed reporting.
• bash <(curl -s https://codecov.io/bash): This is the core command that downloads and runs the Codecov upload script. This script will:
  • Detect that it’s running in CircleCI.
  • Automatically find your CODECOV_TOKEN environment variable.
  • Locate your coverage reports (it looks for common formats like coverage/lcov.info, coverage/clover.xml, etc., in your project’s root directory).
  • Upload the reports to Codecov.

Important Notes:

• Coverage Report Location: Ensure your testing framework is configured to output coverage reports in a location that the Codecov script can find. Common locations are coverage/, reports/coverage/, or directly in the root. If your report is in a non-standard location, you might need to specify it using the CI_REPORTER_OPTIONS environment variable or by moving the report to a standard location before the upload step.
• Test Command: The command npm test -- --coverage is an example. Adjust this to match how your project generates coverage reports. For instance, if you use Jest, this is a common way to invoke it with coverage enabled.
• Docker Image: Make sure the Docker image you use (cimg/node:18.17.1 in the example) has the necessary tools installed (like curl and bash) to execute the Codecov script. Most standard images will have these.

4. Commit and Push

Commit your .circleci/config.yml file and push it to your repository. The next time your CI pipeline runs, it will execute these steps, and you should see your coverage reports appearing on your Codecov dashboard.

5. Verifying the Upload

After a successful build, navigate to your repository on Codecov. You should see a new commit with coverage information. If there are any issues, Codecov usually provides feedback directly on the commit or in its dashboard.

This integration ensures that your code coverage metrics are always up-to-date with your latest commits, helping you maintain and improve your code quality.

The next thing you’ll likely want to configure is branch-based reporting and setting up status checks to fail your build if coverage drops below a certain threshold.