Deprecation Notice and Schedule

🚧

Deprecation Notice

Support for the Bash Uploader will be deprecated on February 1st, 2022.

Please refer to the main Codecov Uploader page for implementation and upgrades.

With the Codecov Uploader released, the Bash Uploader will now undergo the following deprecation plan:

• Sept 1, 2021, to Nov 1, 2021: Codecov will conduct scheduled brownouts of the Bash Uploader. At predetermined times throughout the week, the Bash Uploader will not function. These brownout periods will initially have at least a one-week notice, before occurring but advanced notice times will decrease throughout this three-month period. Each brownout period will be publicly broadcast to users, though.
• Nov 1, 2021, to Feb 1, 2022: Codecov will conduct random unscheduled brownouts of the Bash Uploader. With no announcement or prior disclosure, the Bash Uploader will not function.
• Feb 1, 2022, and onward: The Bash Uploader will be fully sunset and will no longer function.
• Note that this deprecation plan may be subject to change, but those changes will be broadcast to our user base with at least two weeks’ notice. If at any time during the deprecation window use of the Bash Uploader comprises <10% of all uploads to Codecov, we may accelerate the deprecation plan and sunset the Bash Uploader faster than anticipated.

Additional context around this release and change can be found on our blog.

Introduction

The Codecov Bash uploader provides a language-agnostic alternative for sending your coverage reports to Codecov. 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).

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)

Loading token from a 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.

• Using Docker? Please review Testing with Docker.
• Using Python Tox? Please review Testing with Tox.

Finding reports and specifying file names

Codecov can automatically detect coverage files in your project. A thorough filename search will grab everything that is known to be a coverage report. You can also specify exactly which file(s) should be uploaded.

Here are some options for discovering report files:

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

Validating the bash script

The Codecov bash uploader is open source, and it can be validated for correctness by calculating the
SHASUM on download and comparing to the result we store in the GitHub repository.

You can calculate the checksum on download by running

curl https://codecov.io/bash | shasum -a 512
# Codecov provides SHA1, SHA256, and SHA512 hashes

This will not check against the provided checksums provided by Codecov that are located in GitHub.

You can compare the result to the publicly posted values at https://github.com/codecov/codecov-bash/blob/{{ VERSION }}/SHA512SUM. We calculate and publish the SHA1, SHA256, and SHA512 checksums.

For builds with the versions of shasum that support the --ignore-missing flag, you can also verify the checksums by running

curl -fLso codecov https://codecov.io/bash;
VERSION=$(grep -o 'VERSION=\"[0-9\.]*\"' codecov | cut -d'"' -f2);
for i in 1 256 512
do
  shasum -a $i -c --ignore-missing <(curl -s "https://raw.githubusercontent.com/codecov/codecov-bash/${VERSION}/SHA${i}SUM")
done

For older shasum versions, you can run

curl -fLso codecov https://codecov.io/bash;
VERSION=$(grep -o 'VERSION=\"[0-9\.]*\"' codecov | cut -d'"' -f2);
for i in 1 256 512
do
  shasum -a $i -c <(curl -s "https://raw.githubusercontent.com/codecov/codecov-bash/${VERSION}/SHA${i}SUM" | grep -w "codecov")
done

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 processing and formatting (e.g. xcode, python).
3. Reports are found in the filesystem.
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.