Codecov

Code coverage done right.®

Welcome to Codecov Documentation. You'll find comprehensive guides and documentation to help you start working with Codecov as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

About the Codecov yaml

One file to rule them all...configuration that is.

There are two primary locations for the Codecov Yaml. The Team Yaml and the Repository Yaml. Each play an important role in how to configure Codecov.

Default yaml

Below is the default configuration for all projects in Codecov. You may override any of these configuration in your own Team/Repository Yaml.

codecov:
  notify:
    require_ci_to_pass: yes

coverage:
  precision: 2
  round: down
  range: "70...100"

  status:
    project: yes
    patch: yes
    changes: no

parsers:
  gcov:
    branch_detection:
      conditional: yes
      loop: yes
      method: no
      macro: no

comment:
  layout: "header, diff"
  behavior: default
  require_changes: no

Team yaml

Codecov provides a user interface to adjust a "team yaml" which is overrides the defaults set by Codecov and is applied to all repositories in the team. Only team admins can adjustment the team yaml in Codecov. All changes are stored in history.

The most common use for the team yaml is to set up a Codecov Bot account and adding custom CI services.

The team yaml (seen in the black box above) can be found in your account center. `/account/gh/OWNER/yaml`

The team yaml (seen in the black box above) can be found in your account center. /account/gh/OWNER/yaml

Repository yaml

Each repository may have their own, unique, Codecov Yaml. The contents of the Repository Yaml are stored in a file, checked into git/hg.

`codecov.yml` or `.codecov.yml` in the project root or any subdirectory

codecov.yml or .codecov.yml in the project root or any subdirectory

All configuration in the Repository Yaml will override the Team Yaml. The Team Yaml is not replaced, but updated with the Repository Yaml.

# Team Yaml
coverage:
  round: down
  precision: 5

# Repository Yaml
coverage:
  round: up
  range: 0..10

# Used in Codecov after updating
coverage:
  round: up
  range: 0..10
  precision: 5

Validate your repository yaml

Validate your repository yaml by posting the content to Codecov for analyzation.

curl --data-binary @codecov.yml https://codecov.io/validate

Master copy

Codecov will use the default branch for your repository as the "master" copy of the repositories Codecov Yaml. The default branch, if not otherwise stated, is the master branch. You can change the Codecov default branch in your Yaml.

codecov:
  branch: stable

The default branch is used for:

  1. Which branch to cache the repository yaml for UI changes
  2. Which branch is the first branch on the repository dashboard in Codecov

Restricting changes

By default Codecov will always use the current yaml on the branch being tested. If you would like to restrict changes to the yaml and always use the yaml on a specific branch you may declare the branch like this:

codecov:
  strict_yaml_branch: master  # only use the latest copy on master branch

Frequently asked questions

Can I name the file .codecov.yml?

Yes you can name the file either codecov.yml or .codecov.yml. The file can be placed anywhere in your repository.

What is the purpose of the codecov.yml file?

The Codecov Yaml file is the single-point of configuration and gives developers a transparent and version controlled file to adjust all Codecov settings.

Do I need a codecov.yml file?

Nope. Review our default yaml which all projects use. However, if you need to customize your project in Codecov or add new notifications then the yaml is required.

About the Codecov yaml

One file to rule them all...configuration that is.