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.

Instance-Wide Admins

🚧

Instance-Wide admins are only available on Codecov v5.0 and later

The following configuration is only valid for v5.0 releases of Codecov Self-Hosted and later

Codecov uses instance-wide admins in order to manage users, their activation status, and other settings across all orgs. These admins must be defined in the codecov configuration yaml per service.

setup:
  admins:
    - service: github
      username: username1
    - service: github
      username: username2

Your instance must have at least one instance-wide admin in order to function properly. If an admin is not set, a banner will be shown in the Codecov UI indicating as such.

Instance wide admins will see a couple things unique to them, They will have access to an instance-wide user management page, seen below. You'll notice in the top right there's an admin cog to take you here and there's a constantly visible indicator of available seats. This "Users" tab allows you to activate or deactivate any user from any org within your instance all within one screen. The "Access" tab is simply a list of current instance-wide admins.

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 instance yaml

setup:
   max_sessions: 150 #default

If you are instead using envars, you can use:

SETUP__MAX_SESSIONS=150

IPV6 Disable for Frontend

Some environments may not have ipv6 enabled. The default deployment for the Frontend has it enabled. To disable attempting to bind ipv6 please include the following env vars to your container/deployment for Frontend.

name: CODECOV_FRONTEND_IPV6_DISABLED
value: true