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/CD,
• uploaded coverage to Codecov,
• and viewed coverage reports on Codecov and in your pull requests.

Prerequisites

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

1. An understanding of Code Coverage
2. Access to a repository with GitHub, Bitbucket, or GitLab.
3. A CI/CD provider that
   • runs tests and
   • collects 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 yet setup on the right toggle.

GitHub users
If you are signing up via GitHub, you may need to request access from an admin to authorize Codecov as a third-party application. For more information see GitHub OAuth Admin Authorization or follow our video guide.

Step 2: Get the repository upload token

This step can be skipped if you are getting set up on a public repository using one of the following CI/CDs: Appveyor, Azure Pipelines, CircleCI, CirrusCI, GitHub Actions, TravisCI

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 the red box for later. It will be used to authenticate and verify coverage reports uploaded for this repository.

Step 3: Setup integration/team bot

In order to communicate between your code host and Codecov, you will need to set up the GitHub App Integration or add a Team Bot for Bitbucket and GitLab.

Step 4: Upload coverage reports to Codecov

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

📘

Pre-built utilities

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

• Bitrise
• CircleCI
• GitHub Actions

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

You can copy the following Linux-based snippets into your CI/CD. For non-Linux setups, we recommend checking the uploader documentation.

We strongly recommend integrity checking the uploader.

# See https://github.com/codecov/example-ci/blob/main/.github/workflows/ci.yml

- name: Upload coverage to Codecov
  uses: codecov/codecov-action@v3

## Be sure to add the Codecov orb
#  orbs:
#    codecov: codecov/codecov@3
#. See https://github.com/codecov/example-ci/blob/main/.circleci/config.yml

- codecov/upload

after_success:
  - curl -Os https://uploader.codecov.io/latest/linux/codecov
  - chmod +x codecov
  - ./codecov

after_test:
  - curl -Os https://uploader.codecov.io/latest/linux/codecov
  - chmod +x codecov
  - ./codecov

- script: |
    curl -Os https://uploader.codecov.io/latest/linux/codecov
    chmod +x codecov
    ./codecov
  displayName: 'Upload coverage to Codecov'

# ...
  script:
    # ...
    - curl -Os https://uploader.codecov.io/latest/linux/codecov
    - chmod +x codecov
    - ./codecov

An example of a workflow using the uploader 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@v1
    - 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://uploader.codecov.io/latest/linux/codecov
        chmod +x codecov
        ./codecov -t ${CODECOV_TOKEN}

You can check out some of our example repositories for more help on this step.

Step 5: Get coverage analysis from Codecov

After making the above edits, commit your changes and run your CI/CD pipeline. You should see something similar in the build logs

In your pull request, you should see two status checks like

and a pull request comment similar to

Step 6: View the dashboard on Codecov

After merging the above pull request, go back to Codecov and view the dashboard of your repository to see trends in coverage over time.

You can also view coverage for individual commits and pull requests, as well as coverage overlays to get a better understanding of what code hasn't been tested.

🚧

Not seeing coverage on the dashboard?

Go to the Settings tab in Codecov and double-check that the default branch is properly set.

Tips and Tricks

1. Not ready to start using blocking status checks? Set them as informational while you and your team get started with code coverage.

coverage:
  status:
    project:
      default:
        informational: true
    patch:
      default:
        informational: true


# When modifying this file, please validate using
# curl -X POST --data-binary @codecov.yml https://codecov.io/validate

2. Check out our recipe list for common configuration questions.

3. Enforce relative or absolute targets and thresholds during your CI build using the Codecov YAML

4. Use flags to categorize reports in a single repository. This is great for monorepos or projects that include different types of test coverage (e.g., unit, end to end, integration).