Self-Hosted Configuration

Overview

Codecov configuration is done through a yaml file or environment variables.

The environment variables must be in the format of CATEGORY__KEY="VALUE", note the two underscores between category and key.

setup:
  codecov_url: "value"
  codecov_api_url: "value" # Codecov version v4.6 and later
  api_allowed_hosts: # Codecov version v4.6 and later
     - "value"
services:
  notifications:
    slack: "value"

If using environment variables, would become:

export SETUP__CODECOV_URL="value"
export SETUP__CODECOV_API_URL="value" # Codecov version v4.6 and later
export SERVICES__NOTIFICATIONS__SLACK="value

Enterprise License

Provided by Codecov staff which is unique to each company. You can request a license key here.

setup:
  enterprise_license: "very-long-license-key"

Codecov URL

The base url of your Codecov Enterprise instance

📘

Do not add a trailing slash

If you are encountering errors on uploads, or clicking links in statuses or comments, confirm you did not add a trailing slack at the end of this value.

setup:
  codecov_url: "https://codecov.your-company.com"
  codecov_api_url: "https://codecov.your-company.com" #needed in Codecov version v4.6 and later

# or you may use an IP address with an optional port
setup:
  codecov_url: "http://192.168.1.1:5000"
  codecov_api_url: "http://192.168.1.1:5000" #needed in Codecov version v4.6 and later

This url is used, primarily, in Commit Status, Pull Request Comments and Notifications as the redirect url to get back to your Codecov.

Add custom CI domains

An important part of Codecov's process is to check the CI status of commits in order to ensure coverage data is complete and generated by a successful CI build. Add you CI domains in the configuration to ensure they are properly detected.

services:
   ci_providers:
     - jenkins.mydomain.com  # domain name only

Guest Access

By default: all users (logged in or guests) can view reports for public repositories hosted on Github/Bitbucket/Gitlab (not their respective Enterprise products).
You may disable guest access which will require all users to login to your Enterprise instance in order to view any project or interact with the product at all.

setup:
  guest_access: off

Cookie Secret

String used to encrypt secure cookies with. If changed user sessions will exprie and require login to access system again.

setup:
  http:
    cookie_secret: "some-random-string"

Previously at setup.cookie_secret which is automatically copied under http node.

Database

services:
  database_url: postgres://{USER}:{PASSWORD}@{HOST}:{PORT}/{DB_NAME}

The full regular expression the url gets parsed through is the following:

postgres://([\w\-]*):?([\w\-]*)@([\w\-\.]+):?(\d+)/?([\w\-]+)

The regular expression for the user and password is [\w\-]*, some random-generated passwords contain commas and other characters. Please change the password, if necessary, to fit the regular expression above.

Test your string against this regular expression in bash via:

echo "insert-string-here" | python -c "import sys,  re;print('Passed' if re.match('postgres://([\w\-]*):?([\w\-]*)@([\w\-\.]+):?(\d+)/?([\w\-]+)', sys.stdin.read()) else 'Failed');"

Redis

❗️

Redis Cluster Mode is not supported

Due to a lack of cluster mode support in the underlying message queuing system we use, Codecov can not support clustered Redis at this time.

❗️

Encryption in transit not supported

Currently accessing Redis via TLS is not supported.

services:
  redis_url: redis://{USER}:{PASSWORD}@{HOST}:{PORT}/{DB_NAME}

Your Redis instance is used to quickly upload reports for queueing. The instance size of Redis can vary based on (a) size of coverage reports, (b) frequency of uploads, and (c) number of workers processing reports. Recommended 1GB or larger.

The full regular expression is:

redis://([\w\-]*)?:?([\w\-]*)?@?([\w\-\.]+):?(\d+)/?([\w\-]+)

Restrict HTTP Connections

You may restrict the domains that Notifications can connect to.

services:
  notifications:
    slack: "myteam.slack.com"  # can only send messages to myteam.slack.com
    gitter: off  						   # disable gitter notifications
    webhook: "domain.com"      # webhooks can only be sent to domain.com
    irc: off 							 		 # disable irc
    hipchat: off  					   # disable hipchat

Global Upload Tokens

Each Linked Service Provider may have a Global Upload Token to simplify the upload process. To specify your upload token please append a unique string to your service provider.

github_enterprise:
  global_upload_token: "ghe-123abc"

👍

Global Token Upload Settings

When you upload using the global token, you must include the global token AND the owner/repo slug to accept uploads. One option is to supply -r argument, you may also provide this setting in the codecov.yml file.

Not providing the slug of the repo will result in 4xx errors.

curl -Os https://uploader.codecov.io/latest/linux/codecov

chmod +x codecov
./codecov -t ${CODECOV_TOKEN}

Restrict Organizations

You may restrict users to require membership to at least one team/organization.

github:
  organizations:
    - "awesome-team"
    - "modest_mice"

Any user who attempt to login must be a member of either awesome-team or modest_mice. This configuration works for GitHub, Bitbucket and GitLab service providers.

Restrict Teams (GitHub Only)

As of Codecov Enterprise 4.4.6, GitHub and GitHub Enterprise users can restrict login based on organization and team if desired. Team based restrictions will only work if the organization is defined. Otherwise the team list is ignored. Note that both team and organization lists are case sensitive.

github_enterprise:
  organizations:
    - "Great Company"
  teams:
    - "My Great Team"
    
# The following WILL NOT work. Organizations must be supplied as well.
github_enterprise:
  teams:
    - "My Great Team"

🚧

Team Restriction Exists for GitHub and GitHub Enterprise Only

Currently only GitHub and GitHub Enterprise users can use team-based restrictions.

Defining a teams block for any other repository provider in your codecov.yml will likely cause yaml validation to fail.

Note that organization and team checking is inclusive. For example, if you specify multiple organizations and multiple teams, this check will pass if the user belongs to any of the listed organizations and any of the listed teams.

Maximum Number of Uploads (4.6.5 and on)

#in the install yaml

setup:
   max_sessions: 150 #default

If you are instead using envars, you can use:

SETUP__MAX_SESSIONS=150