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

Codecov uses a Yaml-style configuration methodology.

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

Looking for all possible YAML configurations?

See the full codecov.yml Reference page.

Default yaml

The default configuration for all projects in Codecov is demonstrated below. You may override any of these configurations in your own Team/Repository Yaml.

  require_ci_to_pass: yes

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

    project: yes
    patch: yes
    changes: no

      conditional: yes
      loop: yes
      method: no
      macro: no

  layout: "reach,diff,flags,tree"
  behavior: default
  require_changes: no

Team yaml

Codecov provides a user interface to adjust a "team yaml", which overrides the default settings in Codecov. It is applied to all repositories in the team. Only team administrators can adjust 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` in the project root. If placed elsewhere you need to  pass `-y <conf file>` to the bash uploader.

codecov.yml in the project root. If placed elsewhere you need to pass -y <conf file> to the bash uploader.

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

# Team Yaml
  round: down
  precision: 5

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

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

Looking to pass or fail a pull request / merge request based on coverage?

Please see our "Commit Status" feature for passing or failing a pull request based on code coverage thresholds

Validate your repository yaml

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

curl --data-binary @codecov.yml
# PowerShell Sample
Invoke-RestMethod -Uri -Body (Get-Content -Raw -LiteralPath .\codecov.yml) -Method post

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.

  branch: stable

The default branch is used to identify:

  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

Codecov will always use the current yaml on the branch being tested by default. If you would like to restrict changes to the yaml, and always use the yaml on a specific branch, you may declare the branch as shown below.

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

Expired Reports

Codecov will reject reports that are over 12 hours old according to the timestamp in the report. This is to prevent reports that may have been accidently checked into git.

To disable this functionality please add the following to your codecov.yml.

  max_report_age: off

Frequently asked questions

Can I name the file .codecov.yml?

No. Starting the file with a period can cause issues detecting and reading it. The file must be placed the root of your repository to be detected. If you want to place it elsewhere, you must pass -y <conf file> to the bash uploader.

What is the purpose of the codecov.yml file?

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

Do I need a codecov.yml file?

No. 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.

How do I encrypt data that I do not want public?

Head over to your repository settings page; click the Yaml tab. You will find the Create new secret string section in the UI. Information on how to create and use these strings is found in the app.

Updated about a month ago

About the Codecov yaml

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.