Archiving Reports

Introduction

Codecov Self-Hosted stores uploaded coverage reports in a persistent archive. This archive is optional, but much of Codecov's more advanced functionality -- such as overlaying coverage on diffs -- isn't possible without using it.

Starting with version 4.4.0, the archive is supported using minio, which provides an S3-like abstraction to any underlying storage. This allows Codecov to support a myriad of storage back ends that can allow you to tailor report archival directly to your needs and internal requirements.

📘

Cloud Storage is supported by Codecov Self-Hosted v4.4.4 or newer

Codecov Self-Hosted versions 4.4.0 to 4.4.3 do not support S3, Google Cloud Storage, etc as possible storage backends. If you're using one of these versions and wish to leverage cloud storage, it is recommended to upgrade first.

Some minio configuration is unique to v4.4.4+. This configuration is noted inline wherever configuration is displayed below.

🚧

Archived reports may contain source code

Some languages include source code with coverage reports (ex., Swift, gcov, Lua).

General Instructions

There are two basic steps to archive deployment with minio:

1. Setup minio in accordance with your infrastructure/dev ops best practices
2. Provide credentials to access that minio install in your codecov.yml

The codecov.yml configuration for minio is as follows:

services:    
  minio: 
    hash_key: <random string used to obfuscate report data>
    verify_ssl: false # use true for SSL termination on minio 
    host: minio # v4.4.4+ set to host where minio is installed 
    port: 9000
    bucket: archive # bucket name in storage
    region: None # region where bucket is stored (e.g., us-east1)
    access_key_id: "codecov-default-key"
    secret_access_key: "codecov-default-secret"
    dsn: "http://minio:9000" #for v4.4.3 and below only.
    periodic_callback_ms: 10800000 #bool or int. set to false to disable fully
    expire_raw_after_n_days: 30 #int. default is 30 days.

This is the basic configuration for minio. Each of the sections is described below:

• hash_key - a random string used to obfuscate the repositories for which reports are associated. Once this is set and reports are uploaded, do not change it. A default is supplied if this is not specified in your codecov.yml
• verify_ssl - set this to true if you're deploying minio using SSL.
• host - v4.4.4+ the host name of your minio deployment if it is deployed separately from your Codecov Self-Hosted install. Examples include: minio.my-company.com. Defaults to minio
• port - the port number where minio is accessible at host. Defaults to 9000
• region - for cloud storage backends, this is the region where the bucket was created.
• access_key_id - the key used to access the minio ui, doubles as auth for some cloud storage backends. Default is "codecov-default-key", we highly recommend changing this
• secret_access_key - the secret used to access the minio ui, doubles as auth for some cloud storage backends. Default is "codecov-default-secret" we highly recommend changing this.
• periodic_callback_ms - If set to an int, N, Codecov will attempt to periodically delete raw uploads from the archive that are older than expire_raw_after_n_days old every N ms. The default age is thirty days. Setting this to false will preserve all uploaded reports in perpetuity.
• expire_raw_after_n_days - The number of days to keep raw uploaded reports. By default, 30 days. This setting is ignored if periodic_callback_ms is set to false.

🚧

Use Bucket Retention Policy

Although Codecov can clean up the old, raw reports as noted above, we suggest to setup retention policies in your storage provider (such as S3). This process is a lot more efficient, when handled by the storage provider natively, rather than through and external application, which can be resource intensive.

Configuration I: Minio with Docker Volume

The most basic deployment is to use minio as a docker container in your self-hosted docker-compose.yml and back it with a Docker volume. The benefit to this approach is that it's very easy to setup and is generally recommended for the trial or proof of concept stage of your Codecov Self-Hosted deployment.

This is the default setup for archive storage if you follow the Codecov Self-Hosted Deploying with Docker install instructions. There is no need to update any configuration to use minio with a docker volume, it is the default supported use case.

To support minio with a docker volume, the following is used in docker-compose.yml and codecov.yml respectively:

docker-compose.yml

minio:
    image: minio/minio:RELEASE.2018-08-02T23-11-36Z #earliest known working release
    command: server /export
    labels:
      - "traefik.tags=web"
      - "traefik.backend=minio"
      - "traefik.port=9000"
      - "traefik.frontend.rule=PathPrefix: /archive,/minio"
    ports:
      - "9000"
    environment:
      - MINIO_ACCESS_KEY=codecov-default-key
      - MINIO_SECRET_KEY=codecov-default-secret
    volumes:
      - archive-volume:/export
    networks:
      - codecov

Configurable options are as follows:

• volumes - by default Codecov Self-Hosted uses a volume created in the docker-compose.yml file. If you want to use a persistent storage option, such a mounted network drive, you do so by changing the volume parameter: - /path/to/volume:/export
• MINIO_ACCESS_KEY and MINIO_SECRET_KEY in this configuration these are only used as login credentials for the minio browser UI. They can be changed to anything you like as long as the appropriate changes are made in codecov.yml

codecov.yml

services:    
  minio: 
    access_key_id: <minio-access-key>
    secret_access_key: <minio-secret-key>

In the default configuration, the minio configuration in codecov.yml is not needed. However, if you update the MINIO_ACCESS_KEY and/or MINIO_SECRET_KEY you should include those changed values as demonstrated above.

🚧

Configurations II and III assume you're using docker-compose.yml

Configurations II and III detail how to setup minio in your docker-compose.yml backed with S3 or Google Cloud Storage. You can follow the examples below, and the minio docs for other storage options, such as Azure and NAS.

Configuration II: Minio with S3

📘

Create your Bucket First

When using S3 it is important to make sure that your bucket is created before starting Codecov Self-Hosted with minio in this configuration

🚧

The following configuration requires Codecov Enterprise v4.4.4

Using minio with S3 is only available for Codecov Enterprise v4.4.4 and newer

You can use minio with s3 by updating the docker-compose.yml and the codecov.yml.

docker-compose.yml

minio:
    image: minio/minio
    command: gateway s3
    labels:
      - "traefik.tags=web"
      - "traefik.backend=minio"
      - "traefik.port=9000"
      - "traefik.frontend.rule=PathPrefix: /archive,/minio,/<aws-bucket-name>"
    ports:
      - "9000"
    environment:
      - MINIO_ACCESS_KEY=<AWS Access Key>
      - MINIO_SECRET_KEY=<AWS Secret>
    networks:
      - codecov

codecov.yml

services:  
  minio:
    bucket: <bucket-name>
    region: <bucket-region>
    access_key_id: <AWS Access Key>
    secret_access_key: <AWS Secret>
    iam_auth: <boolean, default false>
    port: 443

Important notes:

• The port field is required and if omitted, may result in failed uploads.
• Be sure to substitute <aws-bucket-name> with the S3 bucket you created.
• The MINIO_ACCESS_KEY and MINIO_SECRET_KEY must be set to the AWS Access Key and Secret of an account that can properly access your bucket in S3.
• The access_key_id and secret_access_key in the codecov.yml file must also match the AWS Access Key and AWS Secret provided in the docker-compose-yml
• Alternatively, iam_auth can be set to true when running in AWS. It will attempt to authenticate via the role associated with the instance.

Configuration III: Minio with Google Cloud Storage

📘

Create Your Bucket and Service Account First

Before restarting Codecov Enterprise to use a Google Cloud Storage bucket, make sure that bucket exists and you've created a service account that can properly access the bucket.

🚧

The following configuration requires Codecov Enterprise v4.4.4

Using minio with Google Cloud Storage is only available for Codecov Self-Hosted v4.4.4 and newer.

You can use minio with Google Cloud Storage by updating the docker-compose.yml and the codecov.yml.

In addition to creating the bucket in GCS first, you must take the extra step of creating a Google Cloud Service Account that can access minio. You must also download the corresponding credentials.json file for the service account. The minio documentation outlines how to do this.

After the bucket has been created and you've downloaded the credentials.json file, you can update your docker-compose.yml and codecov.yml

docker-compose.yml

minio:
    image: minio/minio:RELEASE.2018-08-02T23-11-36Z
    command: gateway gcs
    labels:
      - "traefik.tags=web"
      - "traefik.backend=minio"
      - "traefik.port=9000"
      - "traefik.frontend.rule=PathPrefix: /archive,/minio,/<your-bucket-name>"
    ports:
      - "9000"
    volumes:
      - ./path/to/your/credentials.json:/credentials.json 
    environment:
      - GOOGLE_APPLICATION_CREDENTIALS=/credentials.json
      - MINIO_ACCESS_KEY=<minio-dashboard-username>
      - MINIO_SECRET_KEY=<minio-dashboard-pass>
    networks:
      - codecov

codecov.yml

services:
  minio: 
      hash_key: <a-hash-key>
      verify_ssl: <true/false>
      bucket: <your-bucket-name>
      region: <your-bucket-region>
      port: 443
      access_key_id: <minio-dashboard-username>
      secret_access_key: <minio-dashboard-pass>

Important notes:

• Be sure to change /<your-bucket-name> in the docker-compose.yml with the name of the bucket you create in GCS.
• The GOOGLE_APPLICATION_CREDENTIALS envrionment variable should point to the location of the credentials file in the minio container (typically /credentials.json)
• The MINIO_ACCESS_KEY and MINIO_SECRET_KEY are only used to login to the minio UI dashboard in this configuration.
• The port field is required and if omitted, may result in failed uploads.

Configuration IV: External Minio

🚧

The following configuration requires Codecov Self-Hosted v4.4.4

External minio is only supported with Codecov Self-Hosted v4.4.4 and newer.

Finally, it may be desired to run minio outside the default docker-compose setup. This is typically required for more advanced deployments, such as those in kubernetes.

The minio site outlines various deployment strategies that may be of interest, and it is beyond the scope of this documentation to detail each one.

However, if you're going to deploy minio outside of docker-compose, you still need to update the codecov.yml file.

codecov.yml

services:    
  minio: 
    verify_ssl: false # use true for SSL termination on minio 
    host: minio.my-company.com 
    port: 9000
    bucket: <your storage bucket name>
    region: <your bucket region> 
    access_key_id: <your minio access key>
    secret_access_key: <your minio secret key>

Important notes:

• Set verify_ssl to true if you want to use minio with HTTPS. You'll need to follow minio's TLS guide to ensure your minio server is configured properly for this.
• The bucket and region parameters can be ommitted if your hosted version of minio does not use cloud storage.

Migrating Data from an Existing Setup

If you are using an older version of Codecov Self-Hosted and want to migrate your archived report data, please contact us at [email protected], or other communication channels you may already have in place.

In nearly all cases, it is possible with some amount of effort to move legacy archival data to Codecov v4.4.x, and in some cases even migrate that data to a cloud based storage backend.