GuidesAPIChangelogSupportStatusCodecov HomeTry Codecov for Free
Guides

Codecov Self-Hosted Install Guide

Suggest Edits

Prerequisites to Installing Codecov Self-Hosted

PrerequisiteDescription
Basic Ingredients List1. Git-based code host (GitHub.com, Github Enterprise, Gitlab Community Edition, Gitlab Enterprise Edition, Bitbucket, Bitbucket Server)
2. Coverage reports generation
3. A CI provider
Installation Lead Installing Codecov requires deep knowledge of your organization’s infrastructure and how it is implemented, including your CI and Security Configurations. Oftentimes these stakeholders reside on the Operations or SRE team.
Access Controls In order to complete the Codecov install your team will need an account key (provided by Codecov), access to object storage, your Kubernetes Cluster (if applicable) / Compute, Source Control Provider, your Database, and Redis.
Orchestration Managed Kubernetes
Deployment Management Terraform, or, for testing an install, Docker Compose
Software Distribution Access to DockerHub from within your network
Hardware Managed virtual private cloud (AWS, GCP, Azure) with min. 1 machine for installation testing
Database a.) Postgres version 14 or later via managed cloud (e.g., RDS, CloudSQL, or Azure PostgreSQL)

b.) TimescaleDB (optional but highly recommended to use all of Codecov's features)
Cache Redis via managed services (e.g., ElastiCache)
Storage S3 compatible storage (S3, GCS, Azure Blob Storage, Ceph, Minio)

🚧

S3 Compatibility Requirements

Please note, to be able to use any S3 / minio compatible storage, you must be able to grant at least the following policies. The application will not work if any of these cannot be granted.

"s3:GetObject",
"s3:PutObject",
"s3:AbortMultipartUpload",
"s3:ListMultipartUploadParts",
"s3:GetBucketLocation",
"s3:HeadBucket",
"s3:ListBucket",
"s3:ListBucketVersions"

Steps to a Working Implementation of Self-Hosted Codecov

1. Clone our self-hosted repo

2. Setup Required External Services

3. (Optional) Create External Resources

📘

The following steps are optional

Codecov's self-hosted repo comes with containerized services for all of the below resources. If desired, however, these resources can be created externally and added to the codecov.yml configuration.

  • Create an external, managed, postgres database (e.g., AWS RDS, Google Cloud SQL, etc) and have the url with username and credentials in your codecov.yml
  • Create an object storage mechanism (e.g., an AWS S3 bucket, a Google Cloud Storage Bucket, etc) and have the bucket name on hand, plus credentials to supply to the codecov.yml
  • Caveat: If you’re using S3, you can instead ensure codecov runs on a VM with a StorageAdmin S3 role, or using a suitably permissioned* S3 role.
  • Create a separate, managed Redis database (e.g., AWS Elasticache, etc) and have the credentials to supply to the codecov.yml.

4. Create a license

Codecov self-hosted is based on Codecov's Enterprise On-Premises offering which is now deprecated. As a result, this software requires a license to run properly. This is purely a technical requirement of the software at this time and you will never be asked to purchase a license from Codecov or any other entity in order to use Codecov self-hosted.

The installation comes with a general license with a 50 user seat limit. We chose 50 seats as we believe this is the maximum number of users a Docker Compose based PoC can reliably support out of the box, but your mileage may vary depending on how you plan to use Codecov.

If you require more seats, a license.py script has been added that you can use from the command line to generate a license. From the scripts directory, run the following command:

python3 license.py new --expires=2030-12-25 --company=company-name  --users=50

You can set expires, company, and users to whatever future date, name, and user count you wish respectively, but those arguments are required for the script to function properly.

Note that this script requires pycryptodome to be installed on your system. You can install it with:

pip install pycryptodome

5. Edit Configuration

  • Supply the needed configuration derived from the above steps into the codecov.yml

6. Run Codecov

  • Run docker-compose up in the self-hosted root directory.
  • Ensure your codecov installation is working by navigating to it in your browser.

📘

TimescaleDB Migrations must be run manually

If you plan on using TimescaleDB and receive this error after uploading a coverage report, you will need to run the TimescaleDB migrations manually. This is due to Django only running migrations automatically against the default database.

7. Test Codecov

Integrate Codecov into your CI and upload a coverage report
Ensure that Codecov comments and status checks appear on Pull Requests

Updated over 1 year ago

What’s Next