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 Uploader

Introduction

Codecov uses a separate upload tool to make it easy to upload coverage reports to Codecov for processing.

The Codecov Uploader is a statically compiled binary distribution with releases for Linux, Alpine Linux, macOS, and Windows.

Using the Uploader

🚧

It is Highly Recommended to Integrity Check the Uploader

While the snippets below can be used to download and use the uploader directly, it is highly recommended to perform signature and SHASUM verification to ensure integrity of the Uploader before use. See Integrity Checking the Uploader below for more information.

Using the Uploader with codecov.io

For Codecov Cloud users, the Uploader can be invoked as follows:

curl -Os https://uploader.codecov.io/latest/linux/codecov

chmod +x codecov
./codecov -t ${CODECOV_TOKEN}
curl -Os https://uploader.codecov.io/latest/alpine/codecov

chmod +x codecov
./codecov -t ${CODECOV_TOKEN}
curl -Os https://uploader.codecov.io/latest/macos/codecov

chmod +x codecov
./codecov -t ${CODECOV_TOKEN}
Invoke-WebRequest -Uri https://uploader.codecov.io/latest/windows/codecov.exe 
-Outfile codecov.exe
 .\codecov.exe -t ${CODECOV_TOKEN}

The above commands will download the latest version of the Uploader. If you wish to use a specific version of the Uploader, releases can be viewed per distribution here: https://uploader.codecov.io/ .

Pinning to a particular version requires replacing "latest" in the curl command with the specific version numbers, as follows:

curl -Os https://uploader.codecov.io/v0.1.0_4653/linux/codecov

chmod +x codecov
./codecov -t ${CODECOV_TOKEN}

Self-Hosted Use of the Uploader

Note that for Codecov Self-Hosted the Self-Hosted URL will need to be included in the upload command. An example using the Alpine uploader is as follows:

curl -Os https://<your-codecov-self-hosted-url>/latest/alpine/codecov

chmod +x codecov
./codecov -t ${CODECOV_TOKEN} -u https://<your-codecov-self-hosted-url>

Upload Token

📘

Not required for some public uploaders

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 | gitlab | bitbucket>///settings).

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

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

Integrity Checking the Uploader

The new Uploader can be integrity checked against a known GPG key signature, and can also have its contents checked via SHASUM. While performing these two checks is optional, it is highly recommended to do so. By checking the GPG signature and the SHASUM of the uploader, users can be much more confident in the overall integrity of the downloaded file.

At a high level, to integrity check the new Uploader, one must:

  1. Import the Codecov PGP public key (one-time step). The Codecov PGP public key can be retrieved from Keybase or many other keyservers. Key ID: ED779869 Key Fingerprint: 2703 4E7F DB85 0E0B BC2C 62FF 806B B28A ED77 9869
  2. Download the Uploader, SHA256SUM, and SHA256SUM.sig files for your particular distribution
  3. Verify the SHA256SUM file is signed using Codecov’s PGP key
  4. Verify the SHA256SUM in the file matches the Uploader

The following example performs these steps for each distribution of the Uploader's latest version before using the Uploader to upload a coverage report:

🚧

Alpine Linux may Require Additional Dependencies

If the following commands fail when using Alpine Linux, you may need to run: apk add curl gnupg coreutils

🚧

Windows may Require Additional Dependencies

If gpg.exe is not already installed on your system, you can download the Windows GPG client from: https://gnupg.org/download/

curl https://keybase.io/codecovsecurity/pgp_keys.asc | gpg --import # One-time step

curl -Os https://uploader.codecov.io/latest/linux/codecov

curl -Os https://uploader.codecov.io/latest/linux/codecov.SHA256SUM

curl -Os https://uploader.codecov.io/latest/linux/codecov.SHA256SUM.sig

gpg --verify codecov.SHA256SUM.sig codecov.SHA256SUM

shasum -a 256 -c codecov.SHA256SUM

chmod +x codecov
./codecov -t ${CODECOV_TOKEN}
curl https://keybase.io/codecovsecurity/pgp_keys.asc | gpg --import # One-time step

curl -Os https://uploader.codecov.io/latest/alpine/codecov

curl -Os https://uploader.codecov.io/latest/alpine/codecov.SHA256SUM

curl -Os https://uploader.codecov.io/latest/alpine/codecov.SHA256SUM.sig

gpg --verify codecov.SHA256SUM.sig codecov.SHA256SUM

shasum -a 256 -c codecov.SHA256SUM

chmod +x codecov
./codecov -t ${CODECOV_TOKEN}
curl https://keybase.io/codecovsecurity/pgp_keys.asc | gpg --import # One-time step

curl -Os https://uploader.codecov.io/latest/macos/codecov

curl -Os https://uploader.codecov.io/latest/macos/codecov.SHA256SUM

curl -Os https://uploader.codecov.io/latest/macos/codecov.SHA256SUM.sig

gpg --verify codecov.SHA256SUM.sig codecov.SHA256SUM

shasum -a 256 -c codecov.SHA256SUM

chmod +x codecov
./codecov -t ${CODECOV_TOKEN}
Invoke-WebRequest -Uri https://keybase.io/codecovsecurity/pgp_keys.asc -OutFile codecov.asc 
gpg.exe --import codecov.asc

Invoke-WebRequest -Uri https://uploader.codecov.io/latest/windows/codecov.exe -Outfile codecov.exe
Invoke-WebRequest -Uri https://uploader.codecov.io/latest/windows/codecov.exe.SHA256SUM -Outfile codecov.exe.SHA256SUM
Invoke-WebRequest -Uri https://uploader.codecov.io/latest/windows/codecov.exe.SHA256SUM.sig -Outfile codecov.exe.SHA256SUM.sig

gpg.exe --verify codecov.exe.SHA256SUM.sig codecov.exe.SHA256SUM
If ($(Compare-Object -ReferenceObject  $(($(certUtil -hashfile codecov.exe SHA256)[1], "codecov.exe") -join "  ") -DifferenceObject $(Get-Content codecov.exe.SHA256SUM)).length -eq 0) { echo "SHASUM verified" } Else {exit 1}

Arguments

Argument

Usage

-d

Don't upload, output all info on the screen.

-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

-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

-v

Verbose mode

-X FEATURE

Toggle functionalities

-X network Disable uploading the file network

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

-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. Please use the long version to ensure a match between the submitted SHA and the git provider's API response.

-P PR

Specify the pull request number

-T TAG

Specify the git tag

Updated 21 days ago


Codecov Uploader


Suggested Edits are limited on API Reference Pages

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