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

Codecov Bash uploader

Introduction

The Codecov Bash uploader provides a language-agnostic alternative for uploading reports. Its usage is both simple and convenient:

bash <(curl -s https://codecov.io/bash)

The main objectives of the uploader are to:

  • detect the environment
  • gather reports
  • upload them to Codecov

The above command silently requests the latest version of the uploader from Codecov and executes via Bash; all output is directed to stdout.

Upload token

👍

Not Required for some CI Providers

If you have a public project on TravisCI, CircleCI, AppVeyor, Azure Pipelines, or GitHub Actions an upload token is not required.

A unique upload token is required to identify which project the coverage belongs to. This token is located in the repository settings (/<github>/<owner>/<repo>/settings).

A repository on codecov with no uploaded coverage reports. Note the upload token.

There are three ways to provide the upload token to the Bash uploader:

Flag

bash <(curl -s https://codecov.io/bash) -t token

Environment variable

export CODECOV_TOKEN="token"
bash <(curl -s https://codecov.io/bash)

File

echo "token" > .cc_token
bash <(curl -s https://codecov.io/bash) -t @.cc_token

CI detection

The bash uploader detects all CI providers through environment variables. This process helps to identify the source of the build and maintain a relationship back to the source of the coverage collection.

Finding reports

Codecov can automatically detect coverage files in your project. A thorough filename search will grab everything that is known to be a coverage report.

Here are some options for discovering reports:

# only upload this file
-f path/to/foo.bar

# also search this folder that is outside the project directory
-s /home/user/reports/foo/bar

# ignore all files at pattern *.bar
-f "!*.bar"

# include all files at pattern *.foo
-f "*.foo"

Uploading process

When the upload script is called, the general flow is as follows:

  1. The CI is discovered through environment variables.
  2. Language specific process (e.g. xcode, python).
  3. Reports are discovered.
  4. Reports are prepended with file paths and appended with file adjustments.
  5. Reports are uploaded to cloud storage for archiving (secret location).
  6. Codecov is informed of the upload, and will queue the report processing server side.
  7. Done (exit 0).

📘

Exit 0

Codecov will exit 0 to prevent failing the build, if there are issues. If you would like Codecov to exit with 1, use bash <(curl -s https://codecov.io/bash) -Z.

exit 0 is not foolproof. Please use this command to always exit with 0: bash <(curl -s https://codecov.io/bash) || echo 'Codecov failed to upload'.

📘

Verbose mode

If there is an issue with the upload process, it helps to run in verbose mode. Supply the -v flag for better debugging output:

bash <(curl -s https://codecov.io/bash) -v

Arguments

The bash uploader provides various arguments to work with many complex environments. Listed below are the full list of possible arguments and their usage.

Argument

Usage

-A CURL_ARGS

Extra curl arguments to communicate with AWS.

-c

Move discovered coverage reports to the trash

-d

Don't upload, but dump upload file to stdout

-e ENV

Specify environment variables to be included with this build
Also accepting environment variables: CODECOV_ENV=VAR,VAR2

-e VAR,VAR2

-F FLAG

Flag the upload to group coverage metrics
-F unittests This upload is only unittests
-F integration This upload is only integration tests
-F ui,chrome This upload is Chrome - UI tests

-f FILE

Target file(s) to upload
-f "path/to/file" only upload this file
skips searching unless provided patterns below
-f '!*.bar' ignore all files at pattern .bar
`-f '
.foo'` include all files at pattern *.foo

Must use single quotes.
This is non-exclusive, use -s "*.foo" to match specific paths.

-h

Display this help and exit

-K

Remove color from the output

-N

The commit SHA of the parent for which you are uploading coverage. If not present, the parent will be determined using the API of your repository provider. When using the repository provider's API, the parent is determined via finding the closest ancestor to the commit.

-n NAME

Custom defined name of the upload. Visible in Codecov UI

-q PATH

Write upload file to path

-R ROOT_DIR

Used when not in git/hg project to identify project root directory

-s DIR

Directory to search for coverage reports.
Already searches project root and artifact folders.

-t TOKEN

Set the private repository token
(option) set environment variable CODECOV_TOKEN=:uuid

-t @/path/to/token_file
-t uuid

-U CURL_ARGS

Extra curl arguments to communicate with Codecov. e.g., -U "--proxy http://http-proxy"

-v

Verbose mode

-X FEATURE

Toggle functionalities

-X gcov Disable gcov
-X coveragepy Disable python coverage
-X fix Disable report fixing
-X search Disable searching for reports
-X xcode Disable xcode processing
-X network Disable uploading the file network
-X gcovout Disable gcov output
-X html Enable coverage for HTML files

-Z

Exit with 1 if not successful. Default will Exit with 0

enterprise

-r SLUG

owner/repo slug used instead of the private repo token in Enterprise
(option) set environment variable CODECOV_SLUG=:owner/:repo
(option) set in your codecov.yml "codecov.slug"

-S PATH

File path to your cacert.pem file used to verify ssl with Codecov Enterprise (optional)
(option) Set environment variable: CODECOV_CA_BUNDLE="/path/to/ca.pem"

-u URL

Set the target url for Enterprise customers
Not required when retrieving the bash uploader from your CCE
(option) Set environment variable CODECOV_URL=https://my-hosted-codecov.com

env vars

Used to override pre-existing CI environment variables

-B BRANCH

Specify the branch name

-b BUILD

Specify the build number

-C SHA

Specify the commit sha

-P PR

Specify the pull request number

-T TAG

Specify the git tag

gcov

-a GCOV_ARGS

Extra arguments to pass to gcov

-G GLOB

Paths to include during gcov gathering

-g GLOB

Paths to ignore during gcov gathering

-k PREFIX

Prefix filepaths to help resolve path fixing

-p DIR

Project root directory
Also used when preparing gcov

-x GCOVEXE

gcov executable to run. Defaults to 'gcov'

xcode

-D

Custom Derived Data Path for Coverage.profdata and gcov processing
Default '~/Library/Developer/Xcode/DerivedData'

-J

Specify packages to build coverage. Uploader will only build these packages.
This can significantly reduces time to build coverage reports.
-J 'MyAppName' Will match "MyAppName" and "MyAppNameTests"
-J '^ExampleApp$' Will match only "ExampleApp" not "ExampleAppTests"

Updated 3 months ago


Codecov Bash uploader


Suggested Edits are limited on API Reference Pages

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