Get Started

Integrating with Coveralls

Coveralls Builds

The Web App

The API

Get Help

Coveralls API

api-cry

The Coveralls API is organized into several parts, each with a specific purpose:

Use Cases for the Coveralls API

Most users will add their repos to Coveralls through the Coveralls Web UI and configure them there under Repo Settings, eliminating the need to interact with the /repos endpoint.

Likewise, most users will interact with the /jobs endpoint through a Coveralls Integration that posts coverage reports to the Coveralls API for them.

Therefore, this guide is for a smaller set of Coveralls users who may want to:

  1. Programmatically create a new Coveralls repository, perhaps immediately upon its creation at GitHub, and configure it, so coverage reports can be sent for it.
  2. Create a new Coveralls Integration, or extend an existing integration to add new features, or support for a new CI service.
  3. Resolve an issue with a Coveralls Integration, or override its default configuration to support a custom use case.


API Endpoints

The Repos Endpoint

The /repos endpoint is where you can CRUD repositories on Coveralls.

Here, you can set and get basic data on a repo, primarily its name and configuration settings:

Use Case for the Repos Endpoint

This endpoint is useful for automating the creation of a new repository on Coveralls, and configuring it, without using the Coveralls Web UI.

Typical use case: A user writes a script that: (1) programmatically creates a new Coveralls repository, providing any non-default configuration settings; then (2) receives back a JSON representation of the repository along with its repo_token; then (3) uses that token to send coverage reports to Coveralls at the /jobs endpoint.


The Jobs Endpoint

The /jobs endpoint is where you can POST coverage reports (aka. “jobs”) to Coveralls.

Here, you can send a JSON representation of a coverage report to Coveralls, and Coveralls will process it and store it in its database.

Use Cases for the Jobs Endpoint

This endpoint is useful for sending coverage reports directly to Coveralls, without using a Coveralls Integration.

Typical use cases:

  1. A user creates a new Coveralls Integration that posts coverage reports to the /jobs endpoint, or extends an existing integration to add new features.
  2. A user studies the /jobs endpoint to resolve an issue with a Coveralls Integration, potentially to override its default settings and support an atypical use case.


Webhooks

Parallel Build Webhook

The Parallel Build Webhook is a webhook that closes a parallel build.

Use Case for the Parallel Build Webhook

This webhook is useful for closing a parallel build when all of its jobs have completed.

Typical use case: A user configures their Coveralls Integration to handle a parallel build. Their CI build script runs and sends coverage reports in several, related jobs to Coveralls. When all jobs have been sent, the Coveralls Integration sends a request to the Parallel Build Webhook to close the build, which triggers a final, aggregate coverage calculation, completing the build and triggering status updates, PR comments or other types of coveralls notifications.


Rerun Build Webhook

The Rerun Build Webhook is a webhook that triggers a rerun of a build.

  • Resource: Build (build)
  • Actions: POST / GET
  • URI: https://coveralls.io/rerun_build
  • Data format: JSON
  • Authentication: Coveralls Repo Token
  • Full guide: This guide

Use Case for the Rerun Build Webhook

This webhook is useful for rerunning a build that has already been completed.

Typical use case: A user suspects that a build has been incorrectly calculated, perhaps because a parallel build was not processed until after the build was closed. The user sends a request to the Rerun Build Webhook, which triggers a rerun of the build, and sends a new status update to the Github Commit Status API.


JSON-Format Web Data

There are other ways to get JSON-format data from Coveralls besides using the API endpoints.

The following resources are not, strictly defined, API endpoints, but rather, URLs where JSON representations of Web data can be requested from Coveralls.

Note: API Authentication is not required to access these resources, but you must be logged into the Coveralls Web app as a user to access them; so, in that sense, they do require authentication via the OAuth token you receive at login. As such, these are private resources, available only to you and your colleagues with access to your repos.

Repos

You can append .json to the end of any Coveralls Repo URL to get a JSON representation of that repo.

Examples

This representation includes coverage data for the repo’s latest build:

{
  created_at: "2021-04-16T17:46:20Z",
  url: null,
  commit_message: "Bump up version of Coveralls Github Action to v1.1.2 to avoid warning about `flag-name` missing from valid inputs. ",
  branch: "migrate-ci-to-github-actions-use-coveralls-action",
  committer_name: "James Kessler",
  committer_email: "afinetooth@gmail.com",
  commit_sha: "7d6023ed4658f12bdfc1c363de54e4eb36934024",
  repo_name: "lemurheavy/coveralls-ruby",
  badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_91.svg",
  coverage_change: 0,
  covered_percent: 90.88235294117646
}


Including the ?page=1 query parameter will get you the most recent 10 builds for the repo, and you can increment the page number to get the next 10 builds, and so on:

{
  page: 1,
  pages: 36,
  total: 357,
  builds: [
    {
      created_at: "2021-04-16T17:46:20Z",
      url: null,
      commit_message: "Bump up version of Coveralls Github Action to v1.1.2 to avoid warning about `flag-name` missing from valid inputs. ",
      branch: "migrate-ci-to-github-actions-use-coveralls-action",
      committer_name: "James Kessler",
      committer_email: "afinetooth@gmail.com",
      commit_sha: "7d6023ed4658f12bdfc1c363de54e4eb36934024",
      repo_name: "lemurheavy/coveralls-ruby",
      badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_91.svg",
      coverage_change: 0,
      covered_percent: 90.88235294117646
    },
    {
      created_at: "2021-04-16T17:34:07Z",
      url: null,
      commit_message: "Switch from Travis to Github Actions for the gem’s CI:",
      branch: "migrate-ci-to-github-actions-use-coveralls-action",
      committer_name: "James Kessler",
      committer_email: "afinetooth@gmail.com",
      commit_sha: "7e0559029625ce3dbf1f46f1ef448f4ecc8a58f9",
      repo_name: "lemurheavy/coveralls-ruby",
      badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_91.svg",
      coverage_change: 90.9,
      covered_percent: 90.88235294117646
    },
    {
      created_at: "2021-04-13T18:45:20Z",
      url: null,
      commit_message: "Merge pull request #167 from afinetooth/add-merge-request-support-for-gitlab-ci: Add merge request support for Gitlab CI. Ignore failing coverage thresholds at Coveralls. This is a result of recent changes at Travis as they shutdown the .org service.",
      branch: "master",
      committer_name: "GitHub",
      committer_email: "noreply@github.com",
      commit_sha: "6453624810be9862842874f0c812c7af45c5cadb",
      repo_name: "lemurheavy/coveralls-ruby",
      badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_0.svg",
      coverage_change: 0,
      covered_percent: 0
    },
    [...]
    ]
}


Builds

Appending .json to the end of any Coveralls Build URL returns a JSON representation of that build.

Examples

{
  created_at: "2015-06-23T18:33:38Z",
  url: null,
  commit_message: "swap SSLv23 for TLSv1 version bump",
  branch: "v0.8.2",
  committer_name: "Nick Merwin",
  committer_email: "n@mer.io",
  commit_sha: "2ea77ec5eeea2351de50b268994ba69f876b815c",
  repo_name: "lemurheavy/coveralls-ruby",
  badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_91.svg",
  coverage_change: 90.9,
  covered_percent: 90.94076655052265
}


For easier programmatic access, you can substitute the build’s commit sha for its numerical ID, and get the same result:

{
  created_at: "2015-06-23T18:33:38Z",
  url: null,
  commit_message: "swap SSLv23 for TLSv1 version bump",
  branch: "v0.8.2",
  committer_name: "Nick Merwin",
  committer_email: "n@mer.io",
  commit_sha: "2ea77ec5eeea2351de50b268994ba69f876b815c",
  repo_name: "lemurheavy/coveralls-ruby",
  badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_91.svg",
  coverage_change: 90.9,
  covered_percent: 90.94076655052265
}


Jobs

Appending .json to the end of any Coveralls Job URL returns a JSON representation of that job.

Example

{
  repo_name: "lemurheavy/coveralls-ruby",
  full_number: "225.2",
  timestamp: "2015-06-23T18:33:32Z",
  covered_percent: 90.74733096085409
}


Source Files

Appending .json to the end of any Coveralls Source File URL returns a JSON representation of that source file’s coverage.

Examples

This representation includes the source file’s coverage data, only. The same data used to annotate the source file in Coveralls UI.

[ 1,1,1,null,1,null,1,1,null,0,null,1,7,7,7,7,7,2,null,2,null,3,null,7,null,1,null,null,1,null,3,0,0,null,0,null,null,null,3,3,7,null,null,7,null,null,7,null,null,7,null,null,null,null,null,null,null,null,null,null,null,7,null,null,null,null,null,null,null,null,null,3,3,null,3,null,null,0,null,null,1,1,1,1,null,0,1,1,1,null,1,null,null,1,3,null,null,1,14,14,null,null,null,null,null
]

How to read this data:

In this coverage array, the index of the array corresponds to the source file line number. An integer value indicates the number of times the line was executed by tests; and null indicates the line is not relevant.

Note: We don’t store any source code at Coveralls, so the source file’s contents are not included in this representation. When you view the source file through the Coveralls UI, we are fetching the source code in real-time from your git host only for the scope of the request, and only because your token’s permissions allow us to do so.


Passing the filename parameter returns the same type of result:

[ 6,6,6,null,6,null,6,6,null,0,null,6,42,42,42,49,42,12,null,12,null,18,null,42,null,6,null,null,6,null,18,0,0,null,0,null,null,null,18,18,42,null,null,42,null,null,42,null,null,42,null,null,null,null,null,null,null,null,null,null,null,42,null,null,null,null,null,null,null,null,null,18,18,null,18,null,null,0,null,null,6,6,6,6,1,0,5,6,6,null,6,null,null,6,21,null,null,6,84,84
]


Substituting the commit sha for the Build ID works the same:

[ 6,6,6,null,6,null,6,6,null,0,null,6,42,42,42,49,42,12,null,12,null,18,null,42,null,6,null,null,6,null,18,0,0,null,0,null,null,null,18,18,42,null,null,42,null,null,42,null,null,42,null,null,null,null,null,null,null,null,null,null,null,42,null,null,null,null,null,null,null,null,null,18,18,null,18,null,null,0,null,null,6,6,6,6,1,0,5,6,6,null,6,null,null,6,21,null,null,6,84,84
]


Source File Directories & Paths

Aggregated coverage data, across a collection of source files, can be queried, for builds and for jobs, using the paths parameter, which accepts a comma separated list, or glob style format (using wildcard chars):


Examples:

This example retrieves aggregate coverage for two specific source files:

{
        created_at: "2017-04-27T21:20:04Z",
        url: null,
        commit_message: "better jenkins support",
        branch: "master",
        committer_name: "Nick Merwin",
        committer_email: "n@mer.io",
        commit_sha: "6c8775b00c49ab88d6a76e9d0246a261565707e0",
        repo_name: "lemurheavy/coveralls-ruby",
        badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_91.svg",
        coverage_change: 0.05,
        covered_percent: 91.07142857142857,
        paths: "lib/coveralls/simplecov.rb,lib/coveralls/configuration.rb",
        selected_source_files_count: 2,
        paths_covered_percent: 88.14,
        paths_previous_covered_percent: 87.94093519278097,
        paths_covered_percent_change: 0.19
}


This example retrieves aggregate coverage for all source files in the lib/coveralls directory:

{
        created_at: "2017-04-27T21:20:04Z",
        url: null,
        commit_message: "better jenkins support",
        branch: "master",
        committer_name: "Nick Merwin",
        committer_email: "n@mer.io",
        commit_sha: "6c8775b00c49ab88d6a76e9d0246a261565707e0",
        repo_name: "lemurheavy/coveralls-ruby",
        badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_91.svg",
        coverage_change: 0.05,
        covered_percent: 91.07142857142857,
        paths: "lib/coveralls/*",
        selected_source_files_count: 24,
        paths_covered_percent: 90.15,
        paths_previous_covered_percent: 90.04214963119072,
        paths_covered_percent_change: 0.1
}


 

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