Get Started

Integrating with Coveralls

Coveralls Builds

The Web App

The API

Get Help

Supported CI Services

Coveralls was designed to work with all CI services.

The following CI services are officially supported in at least one Coveralls Integration: *

However: Not all CI services are officially supported in all Coveralls Integrations.

If you discover that your Coveralls Integration does not officially support your CI service out-of-the-box, all is not lost. Getting it to work is likely a small matter of manual configuration.

* See the Officially Supported CI Services by Integration table below for a list of officially supported CI services by Coveralls Integration.

Automatic Configuration (Official Support)

Official Support = Automatic Configuration

Automatic configuration is what we mean when we say that a CI Service is officially supported by a Coveralls Integration.

Automatic configuration means that, without any manual configuration on your part, your Coveralls Integration will recognize your CI environment and confgure itself to work with it, making integrating Coveralls with your codebase as easy as it could be.

This ideal situation literally means that the only configuration left to do on your part is to set your Coveralls Repo Token—a requirement for all Coveralls Integrations regardless of CI service.

Officially Supported CI Services by Integration

The following, non-exhaustive list* shows which CI services are officially supported by the most popular Coveralls Integrations: **


IntegrationOfficially Supported CI Services

Coveralls Github Action

Coveralls Orb for CircleCI

Coveralls Universal Reporter

Configure additional CI services with:

node-coveralls

Configure additional CI services with:

coveralls-ruby

Configure additional CI services with:

coveralls-python

Configure additional CI services with:

php-coveralls

Configure additional CI services with:

coveralls-maven-plugin

Configure additional CI services with:

goveralls

Configure additional CI services with:

* With 30+ Coveralls language integrations available, this table is not exhaustive. If you’d like to help us complete it, please send us your contributions.

** This table may occasionally fall out-of-date, so we recommend checking your integration to see if it has added support for your CI service. Even better, why not open a PR on the project and contribute support for your CI service?

Manual Configuration

Important: Check first.
Always check to see if your desired Coveralls Integration has built-in support for your CI Service. If it does, you can save yourself the trouble of manual configuration and let the integration do it for you (~automagically~). Otherwise:

What To Do If Your Coveralls Integration Doesn’t Officially Support Your CI Service:

Answer: Manually configure your integration to work with your CI service.

You have a few options here:

  1. Use common environment variables
  2. Use a .coveralls.yml file
  3. Do what your integration says to do

Option 1: Use Common Environment Variables

The original spec for Coveralls Integrations recommended supporting a common set of environment variables related to your CI service. As a result, many Coveralls Integrations support these environment variables: *

The CI_ Env Vars (Older Spec)

# -----------------------------------------------------------------------------------------
#  Original set of CI_ environment variables (circa 2013): 
# -----------------------------------------------------------------------------------------
CI_NAME
  # The name of the CI service being used (e.g. "travis-ci", "circleci")
CI_BUILD_NUMBER 
  # The number assigned to the build by your CI service
CI_BUILD_URL 
  # The URL to the build details page at your CI service
CI_BRANCH 
  # The branch or tag for the current commit
CI_PULL_REQUEST (optional)
  # If given, corresponds to the number of the pull request. 
  # Expects a value defined as an integer, e.g.: CI_PULL_REQUEST=42 (recommended)
  # However, for flexibility, any single line string ending with the same integer value can also be used (such as the pull request URL or relative path), e.g.:
  # CI_PULL_REQUEST='myuser/myrepo/pull/42'
  # CI_PULL_REQUEST='https://github.com/myuser/myrepo/pull/42'
  # If not given, the build is assumed to be a push build.

# -----------------------------------------------------------------------------------------
#  Added later:  
# -----------------------------------------------------------------------------------------
CI_JOB_ID (optional)
  # For parallel builds, the number assigned to each job comprising the build. When missing, Coveralls will assign an incrementing integer (1, 2, 3 ...). This value should not change between multiple runs of the build.
CI_COMMIT_ID (optional)
  # The commit SHA of the commit. When missing, Coveralls will attempt to determine the commit SHA from the CI service's environment variables related to the `git` commit.
CI_COMMIT_MESSAGE (optional)
  # The commit message of the commit. When missing, Coveralls will attempt to determine the commit message from the CI service's environment variables related to the `git` commit.  
CI_COMMITTER_NAME (optional)
  # The commit author. When missing, Coveralls will attempt to determine the commit author from the CI service's environment variables related to the `git` commit.
CI_COMMITTER_EMAIL (optional)
    # The commit author's email address. When missing, Coveralls will attempt to determine the commit author's email address from the CI service's environment variables related to the `git` commit.

* Some of the Language Integrations that support the CI_ env vars include coveralls-ruby, coveralls-python, and node-coveralls, while the Official Integrations that support them include the Coveralls Github Action and the Coveralls Orb for CircleCI.

Note: This variable set was later superseded by the COVERALLS_ env vars below.

Examples

The set of appropriate values for these environment variables depends on your CI service.

For example, on Travis CI, you would set them like this:

CI_NAME=travis-ci
CI_BUILD_NUMBER=$TRAVIS_BUILD_ID
CI_BUILD_URL=$TRAVIS_BUILD_WEB_URL
CI_BRANCH=$TRAVIS_PULL_REQUEST_BRANCH
  # if the current job is a pull request, the name of the branch from which the PR originated.
  # if the current job is a push build, this variable is empty ("").
CI_PULL_REQUEST=$TRAVIS_PULL_REQUEST

Sourced from Travis CI Default Environment Variables.

On CircleCI, you’d set them like this:

CI_NAME=circleci
CI_BUILD_NUMBER=$CIRCLE_BUILD_NUM
CI_BUILD_URL=$CIRCLE_BUILD_URL
CI_BRANCH=$CIRCLE_BRANCH
CI_PULL_REQUEST=$CIRCLE_PR_NUMBER

Sourced from CircleCI Built-In Environment Variables.

And on Jenkins, you’d set them like this:

CI_NAME=jenkins
CI_BUILD_NUMBER=$BUILD_ID
  # Or $BUILD_NUMBER ($BUILD_ID preferred since v1.597+) 
CI_BUILD_URL=$BUILD_URL
CI_BRANCH=$CHANGE_BRANCH
  # Or $GIT_BRANCH
  # Or $BRANCH_NAME
  # Or $ghprbSourceBranch if using the Github Pull Request Builder Plugin
CI_PULL_REQUEST=$CHANGE_ID
  # Or $ghprbPullId if using the Github Pull Request Builder Plugin

Sourced from Jenkins Set Environment Variables and Jenkins Docs references 1, 2, 3 and 4.

So, the effort here involves researching the environment variables for your CI service and then setting them in your CI configuration file, build script or project settings.


The COVERALLS_ Env Vars (Newer Spec)

Over time, a new set of COVERALLS_ environment variables were specified as replacements for the CI_ env vars.*

These are virtually the same as the CI_ env vars, except that they are prefixed with COVERALLS_, and there are more of them, to support new features added to Coveralls over the same period of time:**

# -----------------------------------------------------------------------------------------
#  Variables matching original CI_ set:
# -----------------------------------------------------------------------------------------
COVERALLS_SERVICE_NAME
  # The name of the CI service being used (e.g. "travis-ci", "circleci")
COVERALLS_SERVICE_NUMBER 
  # The number assigned to the build by your CI service
COVERALLS_GIT_BRANCH (optional)
  # The branch or tag of the current commit
COVERALLS_PULL_REQUEST (optional)
  # If given, corresponds to the number of the pull request. This variable expects a value defined as an integer, e.g.: COVERALLS_PULL_REQUEST=42 (recommended). If not given, the build is assumed to be a push build.

# -----------------------------------------------------------------------------------------
# NOTE: CI_BUILD_URL was not replaced with COVERALLS_BUILD_URL because the URL is not available from all CI environments, and Coveralls opted to start generating the URL from other env vars when it could.

# -----------------------------------------------------------------------------------------
#  Variables added to extend configuration options:  
# -----------------------------------------------------------------------------------------
COVERALLS_GIT_COMMIT (optional)
  # The commit SHA of the commit. When missing, Coveralls will attempt to determine the commit SHA from the CI service environment variables.
COVERALLS_GIT_MESSAGE (optional)
  # The commit message of the commit. When missing, Coveralls will attempt to determine the commit message from the CI service environment variables.
COVERALLS_GIT_COMMITER_NAME (optional)
  # The commit author. When missing, Coveralls will attempt to determine the author name from the CI service environment variables.
COVERALLS_GIT_COMMITER_EMAIL (optional)
  # The commit author's email address. When missing, Coveralls will attempt to determine the author email from the CI service environment variables.
COVERALLS_RUN_AT (optional)
  # The time the build was run. Takes a date string (RFC 3339 dates work). Defaults to your build system's date/time, if available; if unavailable, Coveralls will use the current time.
COVERALLS_RUN_LOCALLY (optional)
#  # A boolean value (true / false) that indicates whether the build is being run locally. When true, Coveralls will not attempt to send the coverage report to the Coveralls API. Useful for testing purposes.
COVERALLS_EVENT_TYPE (optional)
  # The type of event that triggered the build. This can be one of: push, pull_request, api, cron, or web. Defaults to push if not given.

# -----------------------------------------------------------------------------------------
#  Variables added to support parallel builds:  
# -----------------------------------------------------------------------------------------
COVERALLS_SERVICE_JOB_ID (optional)
  # For parallel builds, the number assigned to each job comprising the build. When missing, Coveralls will assign an incrementing integer (1, 2, 3 ...). This value should not change between multiple runs of the build.
COVERALLS_FLAG_NAME (optional)
  # A string that can be used to identify a "job," i.e. a group of tests run in the same build stage.
COVERALLS_PARALLEL (optional)
  # A boolean value (true / false) that indicates whether the build is a parallel build. When true, Coveralls will expect the COVERALLS_SERVICE_JOB_ID to be set for each job comprising the build.
COVERALLS_PARALLEL_FINISHED (optional)
  # A boolean value (true / false) that indicates whether the build is a parallel build that has finished running all jobs. When true, Coveralls will close the parallel build and calculate its aggregate coverage.
COVERALLS_CARRYFORWARD_FLAGS (optional)
 # A comma-separated list of flag names that should be carried forward from a previous build, if its coverage report is missing from the current build. This is useful for parallel builds for monorepos, where not all jobs for all subprojects are run in every CI build.

# -----------------------------------------------------------------------------------------
#  Special variable for use by Coveralls Enterprise customers:
# -----------------------------------------------------------------------------------------
COVERALLS_ENDPOINT (optional)
  # The URL of your Coveralls Enterprise instance. 
  # Value is always https://coveralls.io for Coveralls Cloud users.

# -----------------------------------------------------------------------------------------
#  Required variable for all CI services
# -----------------------------------------------------------------------------------------
COVERALLS_REPO_TOKEN (required)
  # The repository token for your project, as found on the project settings page on Coveralls.
  # This is the only required variable for Coveralls to work.
  # If you are using a private repository, we recommend adding the COVERALLS_REPO_TOKEN to your CI service's protected environment variables.
  # If you are using a public repository, you can add the COVERALLS_REPO_TOKEN to your .coveralls.yml file.

* This change was made to avoid a CI_ prefix clash with the default env vars of some CI services—like GitLab CI and Bitbucket Pipelines—and to claim the COVERALLS_ namespace as best practice.

** Features like Parallel Builds, for which support was also back-ported to the CI_ env vars.


CLI Flags

It’s worth noting here that some Coveralls Integrations don’t support the use of environment variables, per se, because they are offered as Command Line Interface (CLI) only.

If you’re using a CI service that doesn’t support environment variables, you may be able to use the following command line arguments as equivalents:

--service-name
--service-job-id
--service-build-url
--service-branch
--service-pull-request (optional)

You’ll see below that these track closely to the variables recommended for use in a .coveralls.yml file, and are directly related to the JSON input parameters expected in POST requests to the the /jobs endpoint of the Coveralls API.

EXAMPLE

coveralls --service-name travis-pro --service-job-id 1234 --service-build-url https://travis-ci.org/coveralls-clients/coveralls-python/builds/1234 --service-branch master



Option 2: Use a .coveralls.yml file

Another configuration method supported by the majority of Coveralls Language Integrations—and by all Official Integrations—is the use of a .coveralls.yml file.

The .coveralls.yml file

The .coveralls.yml file must simply exist in the root directory of your repo, and can contain the following variables:

# .coveralls.yml
service_name: 
  # Your CI service name (e.g. travis-pro, circleci, etc.)
service_job_id: 
  # Build or Job ID (e.g. $CIRCLE_BUILD_NUM, $TRAVIS_JOB_ID, etc.). 
  # `service_jobs_id` is the more modern option for identifying a build or job. 
service_build_url: 
  # URL to build details. (e.g. $CIRCLE_BUILD_URL, $TRAVIS_BUILD_WEB_URL, etc.)
  # No longer required, but available for backwards compatibility.
service_branch: 
  # The branch of the current commit. (e.g. $CIRCLE_BRANCH, $TRAVIS_BRANCH, etc.)
service_pull_request: 
  # The pull request number (e.g. $CIRCLE_PR_NUMBER, $TRAVIS_PULL_REQUEST, etc.)
  # Only required for pull requests.

repo_token: 
  # We recommend only storing repo tokens for public repos in your .coveralls.yml file. 
  # For private repos, we recommend storing them in your CI service's protected environment variables (aka. secrets).

Note that most of these variable names exactly match those of the JSON input parameters expected in POST requests to the the /jobs endpoint of the Coveralls API.

The values for these variables can be literals, or environment variables, as described above.

Examples

Here’s the simplest example of a .coveralls.yml file:

# .coveralls.yml
repo_token: CCSFM8Axo5Nh6XJKb6U9R6z5fyoDkY6o5

Remember, that a .coveralls.yml file is not required, but if one exists, it might look like this, since the repo_token is the only required variable for Coveralls to work.

Here’s a more involved example of a .coveralls.yml file:

# .coveralls.yml
service_name: circle-ci
service_job_id: $CIRCLE_BUILD_NUM
service_build_url: $CIRCLE_BUILD_URL
service_branch: $CIRCLE_BRANCH
service_pull_request: $CIRCLE_PULL_REQUEST

repo_token: CCSFM8Axo5Nh6XJKb6U9R6z5fyoDkY6o5

Again, we recommend only storing repo tokens for public repos in your .coveralls.yml file. For private repos, we recommend storing them in your CI service’s protected environment variables (aka. secrets).


Option 3: Do What Your Integration Says To Do

Not all Coveralls Language Integrations support the common Coveralls environment variables, or the .coveralls.yml file.

In these cases, you’ll need to follow your integration’s specific instructions for configuring your CI service, or else read its code to understand how it is configured for CI services.

If you’re getting that involved, we encourage you to submit a pull request to your integration’s repo, adding the missing support for your CI service.

If you do that, we’d love to hear about it! (Here’s why.)


The Coveralls Repo Token (Required)

Regardless of which CI Service you’re using, one important requirement for configuring your Coveralls Integration is your Coveralls Repo Token:

Example

COVERALLS_REPO_TOKEN=heiNGAuzaYFuVBBZ53ujChNbPH8cRznDo

Here, we’re passing a repo token as the common environment variable, COVERALLS_REPO_TOKEN, but you can also pass it as the value for the repo_token variable in a .coveralls.yml file.

To reiterate, it doesn’t matter which CI Service you’re using, or whether it is manually or automatically configured. You must provide this this variable somewhere in your environment so it’s available to your integration at build time.

What Is It?

Your Coveralls Repo Token is a hash string that identifies your repo to the Coveralls API and provides security against unauthorized coverage reports.

A unique repo token is assigned to every repo added to Coveralls.

How Does It Work?

In POST requests to its /jobs endpoint, the Coveralls API will only accept coverage report data if the repo_token parameter is present and matches your repo’s unique repo token.

For this reason, we sometimes say the repo token is the “authentication mechanism” for coverage reports. However, it’s important to understand that the repo token is not a standard API token that’s passed in the Authorization header. Instead, it’s passed in the body of the request, with the rest of the data in your coverage report.

Where Do I Find It?

During Setup: Repo Start Page

After adding a new repo to Coveralls, Coveralls generates a dedicated Repo Start Page where you can find your Coveralls Repo Token and grab it for setup purposes:

Repo Token on Start Page
From the Coveralls UI: repo token callout on the Repo Start Page.

After Setup: Repo Page

After you’ve uploaded coverage reports for a repo, you will find your Coveralls Repo Token on your repo’s dedicated Repo Page, with URL form: 

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

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

Which looks like this:

Repo Token on Repo Page

After Setup: Repo Settings Page

Or on your Repo Settings Page, with URL form:

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

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

Which looks like this:

Repo Token on Repo Settings Page

How To Set Your Repo Token

You can pass your repo token in a couple of different ways to ensure it’s picked up by your Coveralls Integration:

We recommend storing the repo token for any private repo in your CI service’s protected environment variables (aka. Secrets):

repo-token-secret Example: COVERALLS_REPO_TOKEN stored as a Secret for Github Actions


As a Literal In Your CI Build Script or .coveralls.yml File

We only recommend this option for public repos.

# .coveralls.yml
repo_token: CCSFM8Axo5Nh6XJKb6U9R6z5fyoDkY6o5

Example: repo_token stored as a literal in a .coveralls.yml file



 

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