Quick Start

This guide is meant to help you get started with Codecov as quickly as possible. By the end of the guide, you will have:

Integrated Codecov into your CI pipeline
Uploaded coverage to Codecov
Viewed coverage reports in Codecov's app as well as in your pull requests / merge requests

Prerequisites

In order to get started, you will need the following:

Access to a repository with GitHub, Bitbucket, or GitLab.
1. If you are a GitHub user you MUST install the Codecov GitHub app for your organization - Codecov can't function without it.
A CI environment that runs tests and generates coverage reports.

📘
Not ready to use Codecov on your own repositories?
Try it out for yourself with the Codecov tutorials for GitHub, Bitbucket, or GitLab to see what Codecov has to offer.

Getting Started

Step 1: Sign up for Codecov

Sign up for a Codecov account to connect your individual code host account with Codecov. You will be brought to a page with a list of repositories.

Not seeing any repositories? Try clicking Not Configured on the left toggle. If you're a GitHub user, you may need to allow additional repositories to access Codecov in the app configuration.. Note that if this is your first time logging into Codecov, it may take a few moments for your repositories to sync and appear in the UI.

Additional Admin Approval for GitHub users
If you are signing up via GitHub and not an admin of your Github organization, you may need to request access from an admin to authorize Codecov as a third-party GitHub application. For more information see GitHub Admin Authorization.

Step 2: Get the repository upload token

Click on setup repo for the repository you would like to use Codecov. This should take you to the setup screen for the repository.

Copy the token as shown in step one for later. It will be used to authenticate and verify coverage reports uploaded for this repository.

Step 3: Setup integration/team bot (GitLab and Bitbucket only)

To communicate between your code host and Codecov, you will need to add a Team Bot for Bitbucket and GitLab.

No further action is required for GitHub users at this step. GitHub utilizes Codecov's GitHub app for this functionality and is handled in Step 1: Signing up for Codecov.

Step 4: Upload coverage reports to Codecov

Use the Codecov CLI and the repository upload token to upload your coverage report(s) to Codecov. These tools should be added as a step in your CI pipeline.

The following CI providers have built-in utilities that will also verify the uploader integrity before uploading to Codecov:

We highly recommend using these built-in Codecov utilities in their respective workflows.

An example of a workflow using the CLI with GitHub Actions is shown below.

name: API workflow

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    name: Test python API
    steps:
    - uses: actions/checkout@v4
    - name: Install requirements
      run: pip install -r requirements.txt
    - name: Run tests and collect coverage
      run: pytest --cov .
    - name: Upload coverage reports to Codecov
      run: |
        # Replace `linux` below with the appropriate OS
        # Options are `alpine`, `linux`, `macos`, `windows`
        curl -Os https://cli.codecov.io/latest/linux/codecov
        chmod +x codecov
        ./codecov --verbose upload-process --fail-on-error -t ${{ secrets.CODECOV_TOKEN }} -n 'service'-${{ github.run_id }} -F service -f coverage-service.xml

You can check out some of our