Coveralls Notifications

Coveralls offers several different types of coverage-related notifications:

Overview

There are 4 types of notifications you can receive from Coveralls:

• Pull Request Comments - Coverage reports, sent directly to your pull requests
• Status Updates - Github commit statuses, with or without checks
• Web Notifications - Slack, Email, Webhook and others
• Badges - Always up-to-date coverage badges for your README’s or dashboards

PULL REQUEST COMMENTS

Found in

Repo Settings—with URL form:

https://coveralls.io/{GIT_SERVICE}/{ORG}/{REPO}/settings

Example: https://coveralls.io/github/coverallsapp/coveralls-demo-ruby/settings

Steps

Follow these steps to enable Pull Request Comments:

1. Enable Settings:

Enable LEAVE COMMENTS? and choose FORMAT:

2. Add the Coveralls Bot to your repo at Github:

1. At GitHub > {Your Repo}, go to Settings > Manage Access.
2. Click Invite a collaborator.
3. Enter “coveralls”
4. Click Add coveralls to {Your Repo}
5. Coveralls will auto-accept your invitation in 5-10 min. ^*

* Coveralls checks for new invitations every 5 min. If your invitation hasn’t been accepted within 10-15 min, shoot us an email and we’ll accept manually.

How can I avoid giving write access to my repo?

If giving the Coveralls Bot write access to your repo is a non-starter for your organization, here’s how to limit its access to read-only, for now^*:

1. Get an org-based subscription - Make sure your Coveralls subscription is associated with a GitHub Organization
2. Add the Coveralls Bot to your org - Go to [Your Github Org] > People > Outside Collaborators, then add the Coveralls Bot (coveralls) to each intended repo with read only access.
3. Verify PR Comments^**

* In Spring 2023 we will introduce a new Github integration based on a Github App, which provides more granular, more secure access to your org resources, and will not require an external bot to leave PR comments.

** This method works for most users. If it doesn’t appear to be working for you, shoot us an email.

3. Verify Pull Request Comments

Create a PR, wait a bit, then make sure you see a PR comment at Github:

* If something looks wrong, check Common Issues & Troubleshooting—or shoot us an email.

STATUS UPDATES

Found in

Repo Settings—with URL form:

https://coveralls.io/{GIT_SERVICE}/{ORG}/{REPO}/settings

Example: https://coveralls.io/github/coverallsapp/coveralls-demo-ruby/settings

Steps

Follow these steps to enable Status Updates:

1. Enable Settings:

Enable USE STATUS API? and, if desired, set COVERAGE THRESHOLD FOR FAILURE^* and COVERAGE DECREASE THRESHOLD FOR FAILURE^*:

Coveralls will now send status updates to Github for each commit.

* If you set failure thresholds, Coveralls will convert the status into a check and report “failed” if the coverage is below the threshold, or if the coverage decreases by more than the threshold.

2. Verify Status Updates / Checks:

Push a new commit to CI, wait a bit, then make sure you see the status updates in the Github UI, and that they pass/fail accordingly:

* If something looks wrong, check Common Issues & Troubleshooting—or shoot us an email.

WEB NOTIFICATIONS

Found in

Repo Settings > Notifications—with URL form:

https://coveralls.io/{GIT_SERVICE}/{ORG}/{REPO}/notifications

Example: https://coveralls.io/github/coverallsapp/coveralls-demo-ruby/notifications

SUPPORTED SERVICES

We currently support notifications via:

• Email - Send a notification via email
• Slack - Send a message to any Slack channel
• Hipchat - Send a message to any Hipchat room
• Gitter - Send a message to any Gitter room
• Webhook - Send a generic JSON payload to any URL <– SUPER FLEXIBLE

HOW TO USE

Just choose the service you want to use and enter the required information.

Examples:

Email Notifications:

Enter the email address you want to receive the notifications. Optionally, make the notifications conditional based on coverage level or decrease.

* You can also enter a comma-separated list of email addresses.

Resulting email notification:

Slack Notifications:

Enter the Slack webhook URL. Instructions on creating a Slack webhook can be found here.

Resulting Slack notification:

Webhook Notifications:

Enter the URL you want to receive your JSON-format message.

Tip: requestb.in is a great service for testing this until you dial it in.

Resulting webhook notification:

BADGES

Badges are the classic way to broadcast the coverage of your project. They’re easy to add to your README and they’re a great way to show off your project’s commitment to quality.

Found in

Repo Page and Repo Settings—with URL forms:

https://coveralls.io/{GIT_SERVICE}/{ORG}/{REPO}
https://coveralls.io/{GIT_SERVICE}/{ORG}/{REPO}/settings

Example: https://coveralls.io/github/coverallsapp/coveralls-demo-ruby
Example: https://coveralls.io/github/coverallsapp/coveralls-demo-ruby/settings

HOW TO USE

Just copy the snippet you need, and paste it where you want it:

It will show up like this and link back to your project at Coveralls:

Any problems, questions or comments about this doc? Let us know.