Get Started

Integrating with Coveralls

Coveralls Builds

The Web App

The API

Get Help

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

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:

settings-pr-comments

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:

pr comments

* 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*:


settings-status-updates


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:

status updates

* 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.

email notif

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

Resulting email notification:

email notif result


Slack Notifications:

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

slack notif

Resulting Slack notification:

slack notif result


Webhook Notifications:

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

webhook notif

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

Resulting webhook notification:

webhook notif result


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:

badge

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

Coverage Status


 


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