Our New Uploader (Beta)
We’ve created an entirely new Uploader using NodeJS that is shipped as a static binary executable on the Windows, Linux, Alpine Linux, and macOS operating systems. Currently, this uploader is in beta, but most standard workflows that are currently accomplished with the Bash Uploader can be accomplished with the new Uploader.
With its beta release, the new Uploader is now the standard, first-party method to upload coverage (and other related data) to Codecov.
We will be deprecating all other language-specific uploaders, with special attention paid to the deprecation of the Bash Uploader (see Bash Uploader Deprecation Roadmap below)
Background Information
For the last 8 months, Codecov has been developing a new uploader that does not rely on the bash script that we currently provide to our customers.
We initiated this project because, as usage of Codecov has grown and our development velocity has increased, the Bash Uploader has become increasingly complex to properly maintain, with the following issues being the most prevalent:
- Bash scripts can be particularly difficult to maintain as they increase in complexity.
- The Bash Uploader, over time, added many “magic features” that were difficult to reason through and support against an ever-increasing number of use cases.
- Bash can be cumbersome to test and properly validate when compared to other languages with tooling more centered on collaborative development.
- The distribution mechanism of choice (i.e., curl pipe to bash) while incredibly convenient, is notoriously problematic from a security perspective.
The weaknesses of the curl | bash approach came to the forefront during a recent security event. To combat this incident from a product perspective we initially provided better documentation on how to verify the Codecov Bash Uploader until our new Uploader was complete, but our ultimate long-term goal has always been to replace the Bash Uploader altogether. Today we are happy to announce that the new Uploader is entering Beta status and is available for public use.
Benefits of the New Uploader
There are a number of benefits to the new Uploader that address some of the security weaknesses of the former bash uploader. Some of these benefits include:
- A compiled binary makes it more difficult for code to be modified by a middle man.
- A more secure, verifiable distribution when compared to the Bash Uploader
- Single codebase in a modern language for all platforms (Windows, Linux, OSX)
- A more robust multi-platform CI/CD pipeline that can properly conduct automated testing of the Uploader in all three major operating environments (i.e., Windows, Linux, OSX). This provides a better tested and validated end product for our users.
- The adoption of NodeJS along with a more modular code architecture allows for a wider body of contributors than was previously possible with Bash.
- Support for multiple environments in other ecosystems – the CircleCI orb, GitHub Action, and Bitrise step will be updated to use the appropriate Uploader binary.
Features of the New Uploader
The new features of the Codecov Uploader, not only address the weaknesses of the former bash uploader but also unify and enhance the numerous language and platform-specific uploaders that are currently available. Some of these features include:
- A natively compiled binary distribution of our Uploader, produced from an open-source NodeJS project to which customers and our community can contribute.
- Consolidation of language-specific uploaders and features into a single Uploader that can be used for all environments.
- Full preservation of all historical versions of the uploader, with provided SHASUMs and GPG Signatures for content and authorship validation if desired.
- Longer-term: availability of the Uploader through trusted operating system package management systems (e.g., APT, Yum, RPM Brew, npm)
How do I Use the New Uploader?
All releases of the new Uploader are available at https://uploader.codecov.io. Use can be pinned to a specific version, or the latest version can be fetched with the appropriate URL. Despite being in beta, many of the command line arguments present in the Bash Uploader are present in the new Uploader as well. The simplest use case for the uploader is to curl it and use it as follows:
For Linux:
curl -Os https://uploader.codecov.io/latest/linux/codecov
chmod +x codecov
./codecov -t ${CODECOV_TOKEN}
Alpine Linux:
curl -Os https://uploader.codecov.io/latest/alpine/codecov
chmod +x codecov
./codecov -t ${CODECOV_TOKEN}
For OSX:
curl -Os https://uploader.codecov.io/latest/macos/codecov
chmod +x codecov
./codecov -t ${CODECOV_TOKEN}
For Windows:
Invoke-WebRequest -Uri https://uploader.codecov.io/latest/windows/codecov.exe
-Outfile codecov.exe
.\codecov.exe -t ${CODECOV_TOKEN}
While the above examples demonstrate the most straightforward way to use the new Uploader, we recommend taking advantage of our new integrity checking measures (see below) to ensure that you are downloading and using a valid, trusted form of the uploader.
How do I Integrity Check the New 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 or many other keyservers. Key ID: ED779869 Key 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 using the latest version of the Codecov Alpine Linux Uploader:
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}
Note that for Alpine Linux you may need to add three specific dependencies as follows:
apk add curl gnupg coreutils
Bash Uploader Deprecation Plan
With the Uploader released, the Bash Uploader will end active support and bug fixes. The bash uploader will be deprecated at a future date.
What About Codecov’s Other Language-specific Uploaders?
Since its release, various community-contributed, language-specific Codecov uploaders have been released. These uploaders are typically re-implementation of the Bash Uploader in a language and package-specific format (e.g., https://github.com/codecov/codecov-ruby and its associated RubyGem). Codecov’s official support for these uploaders will continue until the new Uploader leaves its Beta phase.
If you’re currently using a language-specific uploader for Codecov in your projects, you can continue to do so, but official support for these uploaders will end when Codecov’s Uploader leaves Beta in the future.
What About Ecosystem-specific Uploaders?
Codecov maintains three ecosystem-specific wrappers around the Bash Uploader:
Fundamentally, each of these wrappers invokes the Bash Uploader to upload coverage report files and other information to Codecov.
We will be modifying these wrappers in the future to use the new Uploader instead. A specific timeline on these changes is yet to be released, but this work will be accomplished before the Bash Uploader enters its brownout deprecation period. Today: GitHub Actions, Bitrise Step, CircleCI Orb
We hope that we have maintained the trust of our users these past few months and continue to maintain this trust moving forward by ensuring that anyone who uses Codecov is safe and secure.