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.

๐Ÿ“˜

Dedicated wrappers for the Codecov Uploader

Instead of following the steps below, you can alternatively use a build pipeline-specific wrapper to the uploader to automatically ingest and run the uploader:

Codecov's Github Action v2
Codecov's CircleCI Orb
Codecov's Bitrise Step

Using the Uploader

๐Ÿšง

In case of unexpected behavior (such as "no output in the CI")

Please try to run unset NODE_OPTIONS before running the uploader. This issue is outlined here, and we are working on resolving this ASAP.

https://github.com/codecov/uploader/issues/475

Note: you may also use the -Z param to force non-zero exit code.

Using the Uploader with codecov.io (Cloud)

๐Ÿšง

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.

๐Ÿšง

Default to Success message

Codecov Uploader will default to a "success" message so that we don't block the CI process.

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}
$ProgressPreference = 'SilentlyContinue'
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>/uploader/linux/codecov

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

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

chmod +x codecov
./codecov -t ${CODECOV_TOKEN} --url https://<your-codecov-self-hosted-url>
$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest -Uri https://uploader.codecov.io/latest/windows/codecov.exe 
-Outfile codecov.exe
 .\codecov.exe -t ${CODECOV_TOKEN} --url https://<your-codecov-self-hosted-url>

Upload Token

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

1678

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

Global Upload Token

๐Ÿ“˜

Global Upload Tokens are available on the Cloud Enterprise Plan

Global Upload Tokens are currently only available on Codecov's Enterprise plan. If you're interested in this feature, you can learn more about Codecov's Enterprise plan on our pricing page

A global upload token can be used to upload coverage reports for any repository in an organization. A global upload token can be generated on the Organization Settings page in the Codecov UI. The token is used as follows:

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

chmod +x codecov
./codecov -t <organization_upload_token> -r <org_name>/<repo_name>

## Real example
## ./codecov -t ${CODECOV_TOKEN} -r codecov/example_python

The global upload token can be stored in a CODECOV_TOKEN environment variable and used identically to the repository upload token for any repository in the token's organization. However, the use of the -r parameter to identify the organization and repo is required.

๐Ÿšง

Treat your Global Upload Token as a sensitive credential!

The global upload token is quite powerful, allowing for the successful upload to any repository in the organization for which the token was generated. You should treat this credential as sensitive, and use the appropriate secret management strategies (e.g, Vault, GitHub Secrets, or some other credential storage) as defined by your own internal policies to store it.

You should never commit this credential to source control.

Integrity Checking the Uploader

The 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 --no-default-keyring --keyring trustedkeys.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

gpgv 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 --no-default-keyring --keyring trustedkeys.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

gpgv 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 --no-default-keyring --keyring trustedkeys.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

gpgv codecov.SHA256SUM.sig codecov.SHA256SUM

shasum -a 256 -c codecov.SHA256SUM

chmod +x codecov
./codecov -t ${CODECOV_TOKEN}
$ProgressPreference = 'SilentlyContinue'
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}

Fetching Version Specific Metadata

Metadata can be fetched for a particular release of the Uploader (including latest) as follows:

curl -H "Accept: application/json" https://uploader.codecov.io/alpine/latest  | jq

Which will return a JSON response of the following form:

{
  "artifact": {
    "distro": "alpine",
    "created_at": "2021-08-24 20:58:19",
    "hash": "da09663c04204d349dd26a2e0c2e48e5058429e445602b7961872693a044e17e",
    "file": "codecov-alpine",
    "version": "v0.1.0_8880"
  },
  "link": "https://uploader.codecov.io/v0.1.0_8880/alpine/codecov",
  "file_hash_link": "https://uploader.codecov.io/v0.1.0_8880/alpine/codecov.SHA256SUM",
  "file_sig_link": "https://uploader.codecov.io/v0.1.0_8880/alpine/codecov.SHA256SUM.sig",
  "github_release_link": "https://github.com/codecov/uploader/releases/tag/v0.1.0_8880",
  "hash": "da09663c04204d349dd26a2e0c2e48e5058429e445602b7961872693a044e17e",
  "version": "v0.1.0_8880"
}

The response contains meta information about the particular version in the artifact object, include the distro and the commit SHA of the release, located at https://github.com/codecov/uploader. Links to distributions of the particular version are also provided.

While this is generally useful, the most obvious use case is leveraging this metadata to setup a vendoring pipeline that fetches and verifies latest whenever it updates and stores this verified version of the uploader in an private CDN, filestore, or other storage apparatus.

Uploader Command Line Arguments

Argument nameArgumentDescription
branch-BThis should not commonly be used. Manually specify the name of the branch.
build-bThis should not commonly be used. Manually specify the build number.
changelog-CLDisplay a link for the current changelog
clean-cRemove discovered coverage reports after uploading
dir-sDirectory to search for coverage reports.

Already searches project root and current working directory.
dryRun-dDon't upload files to Codecov
env-eSpecify environment variables to be included with this build.

Also accepting environment variables: CODECOV_ENV=VAR,VAR2'
feature-XToggle different functionalities. Accepts a comma-separated list
-- fixes-X fixesEnable file fixes to ignore common lines from coverage
-- network-X networkDisable uploading the file network
-- search-X searchDisable searching for coverage files
flags-FFlags to use for this upload
file-fTarget file(s) to upload. Can accept multiple files as a comma-separated list.
fullReport-fullSpecify the path of a full Codecov report to re-upload
gcov-gRun with gcov support
-- gcovArgs-gaExtra arguments to pass to gcov
-- gcovIgnore-giPaths to ignore during gcov gathering
-- gcovInclude-gIPaths to include during gcov gathering
-- gcovExecutable-gxgcov executable to run. Defaults to gcov.
name-nCustom defined name of the upload. Visible in the Codecov UI
networkFilter-iSpecify a filter on the files listed in the network section of the Codecov report. Useful for upload-specific path fixing
networkPrefix-kSpecify a prefix on files listed in the network section of the Codecov report. Useful to help resolve path fixing
nonZero-ZExit with a non-zero value if error. Default is false
parent-NThe 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.
pr-PThis should not commonly be used. Manually specify the pull request number.
sha-CThis should not commonly be used. Manually specify the commit SHA
slug-rThis should not commonly be used. Manually specify the slug.
rootDir-RThis should not commonly be used. Manually specify the root directory to search from, in the case that git does not work as expected, or is not found
swift-xsRun with swift coverage support
-- swiftCoverageProject-xspSpecify the swift project to speed up coverage conversion
tag-TThis should not commonly be used. Manually specify the git tag
token-tThe Codecov upload token which can be found in the settings tab of the repository on Codecov.
upstream-UThe upstream http proxy server to connect through
url-uThis should not commonly be used. Change the upload host. Defaults to https://codecov.io
verbose-vRun the uploader with verbose logging
xcode-xcRun with xcode support
-- xcodeArchivePath-xpSpecify the xcode archive path. Likely specified as the -resultBundlePath and should end in .xcresult'