Codecov self-hosted is a docker compose proof of concept, and the readme says so first

The repository says it is a proof of concept before you read anything else

The readme opens with the intent stated plainly: this repo is meant for a quick POC that can be ran locally, and it is recommended to use Helm or Terraform to deploy Codecov in production.

That single line reframes everything else in the repository. The top level holds a docker-compose.yml, a config/ directory, a scripts/ directory, a LICENSE.md and the readme. There is no chart, no Terraform module, no values file and no CI configuration. What you have is a way to run the thing on a laptop, and the project tells you that the real deployment path is elsewhere.

The licence file is another thing to check before you read anything else. The project is recorded under a custom licence that GitHub cannot classify, and there is a LICENSE.md at the root, so you need to read that file yourself rather than assume a standard identifier.

The repository has no GitHub releases, and the last push was on 2026-06-30. It is not archived.

For context on what the stack does, the readme spends its first paragraphs on coverage itself. Coverage reports show which lines of code were tested and which were missed entirely, those reports are uploaded to Codecov to be analysed and stored historically, and the result is described as helping developers track down bugs and commit stronger code. The features section names the parts that land in a developer's workflow: commit statuses and pull request comments, and a Coverage Diff that describes the commit in relation to its impact on tests, which the readme claims improves code reviews.

Four services and the dependencies the API waits for

The compose file gives you the architecture of a Codecov installation, and it is worth reading in full because it is a map of what a self-hosted Codecov actually needs.

The gateway is the entry point. It mounts ./config into the container, sets CODECOV_GATEWAY_MINIO_ENABLED=true, and publishes a port mapping of ${CODECOV_PORT-8080}:8080, meaning the host port falls back to 8080 when CODECOV_PORT is not set. The frontend service points CODECOV_BASE_HOST, CODECOV_API_HOST and CODECOV_IA_HOST at localhost:8080 with CODECOV_SCHEME=http.

The api service is where the dependencies are declared, and the list tells you the data stack.

  api:
    image: codecov/self-hosted-api:latest-calver #note: this is for setup purposes only, be sure to pin to the latest release from our changelog: https://docs.codecov.io/changelog
    volumes:
      - ./config:/config
    networks:
      - codecov
    depends_on:
      - minio
      - timescale
      - postgres
      - redis

So behind the API there is Postgres for the main relational data, Timescale for time series, Redis for caching and queues, and MinIO for object storage. The gateway also depends on api and frontend, and the frontend publishes a port of 8080 on the internal network.

Two comments in the file are instructions rather than explanation. Every image tag carries the note that this is for setup purposes only and that you should pin to the latest release from the changelog, with the changelog URL given. The tags are latest-calver, which is a moving target, and the compose file tells you so in three separate places.

The security disclaimer is the most useful paragraph in the readme

The disclaimer deserves to be quoted in detail, because it is unusual for a vendor to enumerate the ways its own configuration is unsafe.

The configuration is not hardened for security and any usage is at your own risk. Default database credentials are included in the docker compose config, and at a minimum this should be updated before wider usage. The minio bucket is also exposed via the docker compose. The readme explains this is needed for Codecov to function locally, and that while no secret data is stored in this bucket, it is still recommended to make this private and interface with storage via presigned urls. That necessitates using a storage backend such as S3 or GCS.

Three separate weaknesses, then, and each has a named fix: change the database credentials, put the object store behind presigned urls, and move from the bundled MinIO to S3 or GCS.

The SSL path is commented out in the compose file rather than configured. The gateway has a commented volume mount for ${CODECOV_SSL_CERT-/cert/codecov.crt} and a commented port mapping for ${CODECOV_SSL_PORT-8443}:8443, along with a commented CODECOV_GATEWAY_SSL_ENABLED=true. The pattern is consistent: the plaintext path is on by default and the TLS path is a few lines of uncommenting, with the environment variables already named.

The same pattern appears in the frontend service for git providers, with commented lines for CODECOV_GHE_HOST, GITHUB_ENTERPRISE_CLIENT_ID, CODECOV_GLE_HOST, GITLAB_ENTERPRISE_CLIENT_ID, CODECOV_BBS_HOST and BITBUCKET_SERVER_CLIENT_ID.

You must connect a git provider for any of it to work

The usage section states a hard requirement: Codecov currently requires your team to use one or more of GitHub, GitHub Enterprise, GitLab, Gitlab CE, GitLab Enterprise, Bitbucket and Bitbucket Server. You need to configure one or more of these providers for your self-hosted install to function correctly.

That is a meaningful constraint, because Codecov's model is to read coverage reports from a CI run and post statuses back to the provider's pull request. Without a provider there is no commit status and no pull request comment, which are the features the readme leads with.

The compose file gives you the environment variable names for the enterprise variants of each provider, which is where the configuration actually has to happen. The client id variables are for the OAuth application you register with the provider, and the host variables point at your own instance rather than the public one.

The readme also recommends the Self-Hosted Configuration Guide for ensuring a self-hosted install is properly configured, with a link into the Codecov documentation.

The project frames its own history explicitly, in the introductory paragraphs: Codecov has always offered the service free to open source maintainers, and by open sourcing Codecov the company says it is joining the community that supported it from the start, and wants every developer to be able to contribute to and build on the Codecov experience.

Generating a licence, and the 50 seat ceiling it starts from

The licensing situation is unusual enough that it deserves its own section.

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

The installation comes with a general licence with a 50 user seat limit, and the reasoning is given: 50 seats is the maximum number of users the authors believe a docker compose based proof of concept can reliably support out of the box, though your mileage may vary depending on how you plan to use Codecov.

If you need more, there is a license.py script for the command line. From the scripts directory, the invocation is:

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

The expires, company and users arguments can be set to any future date, name and count, but all three are required for the script to work.

The script needs pycryptodome on your system, installed with:

pip install pycryptodome

So the licence is generated locally and cryptographically, with no request to a vendor and no key issued to you. That is a meaningfully different arrangement from the deprecated on-premises product it derives from, and it means a deployment is not blocked on a sales process.

Where the compose stack stops being enough

The gap between this repository and a production installation is large and specific, and it is best understood as a list of things that are present in the compose file only because the deployment does not need to survive a real network.

The first is storage. MinIO is bundled and exposed, which works locally because nothing is stored in it and nothing is untrusted. Anything beyond a trial needs a real object store, S3 or GCS, and the presigned url pattern that the readme asks for.

The second is the database credentials, which are defaults in a committed file.

The third is TLS. The gateway and frontend serve over http by default, with CODECOV_SCHEME=http and no certificate. A production deployment terminates TLS somewhere, and the compose file only offers the commented-out variables to get you started.

The fourth is the image tag. latest-calver is explicitly labelled as being for setup purposes only, and the changelog URL is given so you can pin properly. A production deployment that tracks a floating tag will change behaviour under you.

The alternative is to use Helm or Terraform, as the readme recommends, and to work from the Self-Hosted Configuration Guide rather than from this compose file. The difference in approach is that the compose file is a demonstration of the service graph, whereas a chart or module is a deployment artefact with values, upgrades and rollback. If your question is what a self-hosted Codecov needs in terms of databases, caches and object stores, this repository answers it in a single compose file. If your question is how to run one in production, it points you elsewhere and that is the right answer.

Editorial conclusion

codecov/self-hosted fits a team evaluating whether a self-hosted Codecov is worth the effort, because the whole stack comes up with one compose file and a `config/` directory you can read. It does not fit a production deployment, since the readme states the configuration is not hardened for security, the default database credentials are included, and the minio bucket is exposed. If you intend to go further than a proof of concept, follow the Self-Hosted Configuration Guide and switch storage to S3 or GCS with presigned urls, and generate a licence with `python3 license.py new` when the 50 seat limit is not enough.

Frequently asked questions

Official sources

1. codecov/self-hosted on GitHub
2. Issues
3. README