About the Codecov YAML

Codecov uses a YAML-style configuration methodology.

There are two primary locations for the Codecov YAML:

• Global YAML: The global settings for your organization, accessible via your settings page in Codecov https://app.codecov.io/account/[gh/gl/bb]/[org_name]/yaml

• Repository YAML: The repo level settings for each repo, set and held in your Github/Gitlab/Bitbucket. This YAML file must be a stand-alone file and is not part of your CI-level YAML.

🚧

Global and Repo YAML hierarchy

If both the Global YAML AND the Repository YAML are set, the Repository-level YAML has priority.

👍

Changing your Codecov YAML?

Changing your Codecov YAML? A reminder to always validate your Codecov YAML before you deploy https://api.codecov.io/validate

📘

Looking for all possible YAML configurations?

See the full codecov.yml Reference page.

Global YAML

Codecov provides a user interface to adjust a "Global YAML", which overrides the default settings in Codecov. It is applied to all repositories in the Global. Only Global administrators can adjust the Global YAML in Codecov. All changes are stored in history.

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

Example of Global YAML in settings page

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.

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

# Global YAML [lower on hierarchy]
coverage:
  round: down
  precision: 5

# Repository YAML [higher on hierarchy]
coverage:
  round: up
  range: 0..10

# Used in Codecov after updating
coverage:
  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 https://codecov.io/validate

# PowerShell Sample
Invoke-RestMethod -Uri https://codecov.io/validate -Body (Get-Content -Raw -LiteralPath .\codecov.yml) -Method post

NOTE: This YAML validator is specific to the codecov.yml file. This will not validate your CI-level YAML that you use to upload to codecov.

📘

Validation response codes.

A quick way to determine if the YAML validated against this endpoint is to check the response code. An invalid YAML will return a status code of 400, instead of the normal 200 success.

Default Branch

Codecov will use the default branch from Git for your repository as the primary source of the repositories' Codecov.yml.

You can change the Codecov default branch in your YAML.

codecov:
  branch: stable # set new Default branch

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.

Locking Codecov YAML to a Branch

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.

For example: you may be changing the Codecov YAML on a feature branch to test out Codecov features but want the Codecov configuration to always reference the default branch

codecov:
  strict_yaml_branch: default  # only use the latest YAML on stated 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.

codecov:
  max_report_age: off

Frequently asked questions

Can I name the file .codecov.yml?

Yes. However, the file must still be located in the repository root, dev/, or .github/ directories

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

Why does my bot not match the one I inputted on my YAML?

There are several reasons why the bot specified does not match the one in use:

• The YAML in your repo is invalid. If you included the bot username in a repository-level YAML, please follow the steps here to determine if this repository-level YAML is valid.

  You might also want to consider setting a bot in the organization-level YAML so it's easier to see what’s going wrong.

• The bot is not part of the organization. For a team bot to work, it must be part of the organization your repositories live in.

• The bot was not granted access to the repository you have. To resolve, simply login to Codecov as the bot.

• The bot's access token has expired. To resolve, log into Codecov again as the bot and grant permission.

Why does the current repository YAML not match what I have in my repo?

There are three possible reasons why the YAML you see in the Current repository yaml section of the /settings/yaml page does not match the one you see in your repo:

• The YAML in your repo is invalid. When the repoistory-level YAML is invalid, we keep using the last valid YAML provided. To determine whether your YAML is valid, please follow the steps here.

• The repository-level YAML is not in what Codecov considers the default branch. If the YAML is in a feature branch, you should be able to see it in Current repository YAML section of the /settings/yaml page after merging the feature branch into the default branch. You can identify the default branch in the _Default Branch section of the /settings page.

• Codecov was unable to fetch the new YAML from the repo. This usually happens when the bot user you use (more info) or the provider integration you installed does not have access to the repository in your provider (i.e. GitHub, GitLab, etc). It's also possible you unintentionally specified the wrong bot user.