Notifications

🚧

Notice about delayed notifications

Codecov delays notifications to make sure all reports are uploaded. Learn more at Merging Reports.

📘

Customization of pull request comments?

If you are looking to customize your comments, including turning them off, please see Pull Request Comments

Codecov can send notifications to a variety of different services, all outlined below. For each service, there are a collection of standard fields in addition to fields custom to that service.

This page will first define the custom fields common to all notification systems and then define each service level notification setting in its relevant provider category.

Current supported notification providers out of the box are:

• Slack
• Gitter

You may be able to interact with other types of notification providers using our Standard Notification Fields (below).

Slack

Slack Notifications are now housed in a dedicated app.

It can be installed into your slack workspace from the following url: https://notifications.codecov.io/slack/install. Further info is available in our docs here: Slack Integration.

Gitter

Standard Notification Fields

Note that these standard fields can be supplied for any of the providers defined below.

url: "https://url.to.service"
branches': 
  - master
  - dev
  - staging
threshold': 1%
flags: 
  - backend
  - frontend
base: "parent"
only_pulls: false
paths: "*/**/*"

url

The url to the service, not necessarily applicable to all providers, such as IRC.

branches

The branches you for which you would like to send notifications. Defaults to all branches

threshold

The coverage threshold on which you would like to send a notification. If the coverage changes by more than the amount in the threshold field, a notification will be sent, otherwise it will not. Default to None, which means that notifications will always be sent regardless of coverage change amount.

flags

Specify the flags for which you would like notifications to be sent. Defaults to all flags. see: Flags

base

The base commit type to which you would like to send notifications. Options are 'parent','pr', and 'auto'.

• parent: compare the commit being notified on to its direct parent
• 'pr': compare the commit being notified on to the base of a PR if the commit is in a PR.
• 'auto': automatically choose the appropriate comparison. If the commit being notified on is in a PR, pr will be used, otherwise parent will be used. This is the default.

only_pulls

Notify only on pull requests, default is False

paths

Only send a notification if the specified file paths change. Augments the flags setting. If both flags and paths are specified, a notification will be triggered if files covered by the supplied flags OR paths change.

Basic Configuration

Here is demonstrated the basic configuration for adding a Gitter notification.

coverage:
  notify:
    gitter:
      default:
        url: "https://webhooks.gitter.im/e/9d1957r0a481787c756z"
        threshold: 1%
        only_pulls: false
        branches: 
          - "master"
        flags: 
          - "unit"
        paths: 
          - "src"

Create a Gitter Integration URL

1. Navigate to your room in Gitter. ex. https://gitter.im/codecov/support.
2. Click Room Settings icon (top-right corner).
3. Click Integrations from the dropdown.
4. Click on Codecov from the integration list.
5. Copy the webhook url into your yaml.

Advanced Configuration

All Codecov notifications can be customized. The advanced configuration shown below can be applied to any of the notifications services.

Multiple Notifications

You may create additional notifications that post to different channels with different coverage metrics.

coverage:
  notify:
    slack:
      frontui:
        url: "https://hooks.slack.com/services/T04KHQ16W/B225J94BG"
        flags:
          - frontend
          - ui
      backunit:
        url: "https://hooks.slack.com/services/T04KHQ16W/B225J94BG"
        threshold: 2%  # allow coverage to drop by 2% without posting a notification
        flags:
          - backend

Notice how we added two unique notifications. Each of them are measuring different reports based on Flags.

Preventing notifications until after N builds

You may want to prevent any notifications until after a known number of builds. The after_n_builds option delays notifications for a given commit until a certain number of uploads have been received and processed by Codecov. Some common use cases are:

1. Parallel CI setups
2. Long running CI pipelines that upload to Codecov multiple times

To use after_n_builds in your YAML, follow this example:

codecov:
  notify:
    after_n_builds: 5
# do not notify until at least 5 builds have been uploaded from the CI pipeline
# you can also set after_n_builds on comments independently
comment:
  after_n_builds: 4

In this YAML, at least 5 builds would need to be received before Codecov would push a notification.

Preventing notifications until you're ready to Send-Notifications

Codecov doesn't intrinsically know when you have finished making uploads for a commit, this allows you to tell us. When this is enabled we'll send one PR comment and you'll be notified just one time that we've posted a comment (if you have notifications for PR comments turned on in your code host of choice).

This setting requires that you use the Codecov CLI to upload coverage data to Codecov and is most useful for more complex CI setups. This includes scenarios like:

• You're making many uploads on a commit (50+ reports).
• Uploading some reports on one commit and then different reports on the next and using carryforward flags to paint a full picture of your coverage.
• You're struggling with the notification volume from your code host.

To enable this setting there's two components, the first is a command in the CLI that you should place after the steps where are all uploading of coverage reports is complete.

codecov-cli send-notifications

You'll also need to add the following to your Codecov YAML:

codecov:
  notify:
    manual_trigger: true

This is also noted in the CLI Options page towards the bottom with many of the other ways to utilize our CLI and uploader. If you get stuck, running codecov-cli --help will output the available commands along with the different general options that can be used with them.