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.
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}
wget 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>
wget 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
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.
Note that if you are setting the token as a secret in your repository, bots and non-members may not have access to it. If you are using Dependabot, you may need to add the secret as CODECOV_TOKEN for that bot.
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:
- Import the Codecov PGP public key (one-time step). The Codecov PGP public key can be retrieved from Keybase (https://keybase.io/codecovsecurity/pgp_keys.asc), many other keyservers, our security page (https://about.codecov.io/security/), or our uploader page (https://uploader.codecov.io/verification.gpg). Key ID:
ED779869Key Fingerprint:2703 4E7F DB85 0E0B BC2C 62FF 806B B28A ED77 9869 - Download the Uploader, SHA256SUM, and SHA256SUM.sig files for your particular distribution
- Verify the SHA256SUM file is signed using Codecov’s PGP key
- 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.exeis not already installed on your system, you can download the Windows GPG client from: https://gnupg.org/download/
curl https://uploader.codecov.io/verification.gpg | 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}
wget https://uploader.codecov.io/verification.gpg | gpg --no-default-keyring --keyring trustedkeys.gpg --import # One-time step
wget https://uploader.codecov.io/latest/alpine/codecov
wget https://uploader.codecov.io/latest/alpine/codecov.SHA256SUM
wget 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://uploader.codecov.io/verification.gpg | 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://uploader.codecov.io/verification.gpg -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 | Usage |
|---|---|
| -B, --branch | Specify the branch manually. Used to override pre-existing CI environment variables |
| -b, --build | Specify the build number manually. Used to override pre-existing CI environment variables |
| -c, --clean | Move discovered coverage reports to the trash [boolean] [default: false] |
| -C, --sha | Specify the commit SHA mannually. Please use the long version to ensure a match between the submitted SHA and the git provider's API response. Used to override pre-existing CI environment variables |
| -d, --dryRun | Don't upload files to Codecov [boolean] [default: false] |
| -e, --env | Specify environment variables to be included with this build. Also accepting environment variables: CODECOV_ENV=VAR,VAR2 |
| -f, --file | Target file(s) to upload |
| -F, --flags | Flag the upload to group coverage metrics [default: ""] |
| -g, --gcov | Run with gcov support [boolean] [default: false] |
| --gcovArgs, --ga | Extra arguments to pass to gcov [string] |
| --gcovIgnore, --gi | Paths to ignore during gcov gathering [string] |
| --gcovInclude, --gI | Paths to include during gcov gathering [string] |
| -i, --networkFiler | Specify a filter on the files listed in the network section of the Codecov report. Useful for upload-specific path fixing [string] |
| -k, --networkPrefix | Specify a prefix on files listed in the network section of the Codecov report. Useful to help resolve path fixing [string] |
| -n, --name | Custom defined name of the upload. Visible in Codecov UI [default: ""] |
| -N, --parent | 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. |
| -P, --pr | Specify the pull request number mannually. Used to override pre-existing CI environment variables |
| -Q, --source | Used internally by Codecov, this argument helps track wrappers of the uploader (e.g. GitHub Action, CircleCI Orb) [string] [default: ""] |
| -R, --rootDir | Specify the project root directory when not in a git repo |
| -s, --dir | Directory to search for coverage reports. Already searches project root and current working directory |
| -t, ${CODECOV_TOKEN} | To specify the Codecov upload token |
| -T, --tag | Specify the git tag. Used to override pre-existing CI environment variables [default: ""] |
| -U, --upstream | The upstream http proxy server to connect through [string] [default: ""] |
| -v, --verbose | Run with verbose logging [boolean] |
| -X, --feature | Toggle functionalities. Separate multiple ones by comma: -X network,search -X network Disable uploading the file network -X search Disable searching for coverage files [string] |
| --xcode, --xc | Run with xcode support [boolean] [default: false] |
| --xcodeArchivePath, --xp | Specify the xcode archive path. Likely specified as the -resultBundlePath and should end in .xcresult [string] |
| Self-hosted Enterprise | |
-r SLUG | owner/repo slug used instead of the private repo token in Self-hosted (option) set environment variable CODECOV_SLUG=:owner/:repo(option) set in your codecov.yml "codecov.slug" |
-u URL | Set the target url for Self-hosted customers (option) Set environment variable CODECOV_URL=https://my-hosted-codecov.com |
Updated over 1 year ago