how to get the coverage% of master branch through API?

[LukeGuanY]

I am trying to make a GET request to coveralls API to get the coverage% of a branch/main/master

I went through these two docs, but I couldn't find useful information. Could someone help? https://docs.coveralls.io/api-introduction https://docs.coveralls.io/api-reference

[afinetooth]

Hi @LukeGuanY, you'll want to check out: https://coveralls.io/api/docs

It's linked-to from the top of: https://docs.coveralls.io/api-reference

It sounds like you want GET REPO INFO FROM COVERALLS, however that won't get you the coverage %.

You can get that info from the web app by adding .json to the end of your normal project URL, along with page= and branch= params as needed, like so:

Example:

Normal project URL: https://coveralls.io/github/coverallsapp/coveralls-demo-ruby

Add .json: https://coveralls.io/github/coverallsapp/coveralls-demo-ruby.json

Returns JSON like:

{
    created_at: "2020-10-12T22:55:14Z",
    url: null,
    commit_message: "Merge 6edae2c43cc82ef73be90fd8b51c247e1b51f35e into 
    66 a178736b64aa9cfcefa9cb58ad8d80548df173 ",
    branch: "pull-request-travis-universal",
    committer_name: "afinetooth@gmail.com",
    committer_email: null,
    commit_sha: "9fece0b3dbb517ec9258ee488522830349a08238",
    repo_name: "coverallsapp/coveralls-demo-ruby",
    badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_80.svg",
    coverage_change: -20,
    covered_percent: 80
}

Add page=n param to show all builds: https://coveralls.io/github/coverallsapp/coveralls-demo-ruby.json?page=1

Returns JSON like:

{
    page: 1,
    pages: 2,
    total: 17,
    builds: [{
            created_at: "2020-10-12T22:55:14Z",
            url: null,
            commit_message: "Merge 6edae2c43cc82ef73be90fd8b51c247e1b51f35e into 66a178736b64aa9cfcefa9cb58ad8d80548df173",
            branch: "pull-request-travis-universal",
            committer_name: "afinetooth@gmail.com",
            committer_email: null,
            commit_sha: "9fece0b3dbb517ec9258ee488522830349a08238",
            repo_name: "coverallsapp/coveralls-demo-ruby",
            badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_80.svg",
            coverage_change: -20,
            covered_percent: 80
        },
        {
            created_at: "2020-10-12T22:54:25Z",
            url: null,
            commit_message: "Example pull request. This PR should decrease coverage by 20%.",
            branch: "pull-request-travis-universal",
            committer_name: "afinetooth@gmail.com",
            committer_email: null,
            commit_sha: "6edae2c43cc82ef73be90fd8b51c247e1b51f35e",
            repo_name: "coverallsapp/coveralls-demo-ruby",
            badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_80.svg",
            coverage_change: 0,
            covered_percent: 80
        },
        {
            created_at: "2020-10-12T22:50:38Z",
            url: null,
            commit_message: "Example pull request. This PR should decrease coverage by 20%.",
            branch: "pull-request-travis-universal",
            committer_name: "afinetooth@gmail.com",
            committer_email: null,
            commit_sha: "e84e96caab8e3d56cbda6ec80ce9f5e5e8f3799d",
            repo_name: "coverallsapp/coveralls-demo-ruby",
            badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_80.svg",
            coverage_change: -20,
            covered_percent: 80
        },
        {
            created_at: "2020-10-12T22:47:27Z",
            url: null,
            commit_message: "Merge pull request #1 from coverallsapp/pull-request-travis-universal",
            branch: "travis-universal",
            committer_name: "afinetooth@gmail.com",
            committer_email: null,
            commit_sha: "66a178736b64aa9cfcefa9cb58ad8d80548df173",
            repo_name: "coverallsapp/coveralls-demo-ruby",
            badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_100.svg",
            coverage_change: 20,
            covered_percent: 100
        },
        {
            created_at: "2020-10-12T22:42:38Z",
            url: null,
            commit_message: "Update config.yml",
            branch: "circle-universal",
            committer_name: "afinetooth@gmail.com",
            committer_email: null,
            commit_sha: "09d912cc5235637521d7ed82e9492d8d14f01669",
            repo_name: "coverallsapp/coveralls-demo-ruby",
            badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_80.svg",
            coverage_change: 0,
            covered_percent: 80
        }
    ]
}

Add branch=<branch_name> to show builds on a given branch: https://coveralls.io/github/coverallsapp/coveralls-demo-ruby.json?page=1&branch=master

Returns JSON like:

{
    page: 1,
    pages: 1,
    total: 3,
    builds: [{
            created_at: "2020-04-27T19:32:28Z",
            url: null,
            commit_message: "Update README.md",
            branch: "travis-ci",
            committer_name: "GitHub",
            committer_email: "noreply@github.com",
            commit_sha: "5eaea57de539ad2b8401be46e94e41be6577ef58",
            repo_name: "coverallsapp/coveralls-demo-ruby",
            badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_100.svg",
            coverage_change: 0,
            covered_percent: 100
        },
        {
            created_at: "2020-04-27T19:22:05Z",
            url: null,
            commit_message: "Add tests to make coverage 100%.",
            branch: "travis-ci",
            committer_name: "James Kessler",
            committer_email: "afinetooth@gmail.com",
            commit_sha: "201d1cd9be0c36366f7f8ce023d1e1f0d150de52",
            repo_name: "coverallsapp/coveralls-demo-ruby",
            badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_100.svg",
            coverage_change: 20,
            covered_percent: 100
        },
        {
            created_at: "2020-04-21T00:23:33Z",
            url: null,
            commit_message: "Update gems.",
            branch: "travis-ci",
            committer_name: "James Kessler",
            committer_email: "afinetooth@gmail.com",
            commit_sha: "31aba8151a12fedcf55913758f34cb1c62904ebd",
            repo_name: "coverallsapp/coveralls-demo-ruby",
            badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_80.svg",
            coverage_change: 80,
            covered_percent: 80
        }
    ]
}

[LukeGuanY]

Hi @afinetooth, thanks for the reply. I know this method works for the public repo, but my repo is a private one, which requires the token.

I think this method doesn't work for the private repos. Do you know is there any way that I can send a header with my personal token, not the repo token to get the coverage? Since I need an automatic way to get all the coverage of the repos in my organization.

I checked issues/1189, it seems there is no way to get coverage for private repos.

Thank you.

[afinetooth]

Hi @LukeGuanY here's how it works:

API

The /repos endpoint of the API does require a personal access token, which you pass in a header, like:

'Authorization: token eOHdLJGkyIOirzbKfIJUau0D2CRPXLJCDfqzR'

In the context of a cURL command:

curl --location --request GET 'https://coveralls.io/api/repos/github/afinetooth/coveralls-demo-ruby' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: token eOHdLJGkyIOirzbKfIJUau0D2CRPXLJCDfqzR'

You can obtain your own personal access token from your Coveralls account page.

Web app

The web app does not require a personal access token, but it does require you to authenticate through http, whether manually or through a web crawling script. (repo_token does not apply (see below).)

In other words, that JSON data is only available through the web UI, not through an API endpoint, so you need to get to it differently.

Repo tokens

The only endpoint that requires a coveralls repo_token, when using a private repo, is the /jobs endpoint, which is documented in the API Reference. That's the most commonly used endpoint as it's where all integrations POST coverage reports to coveralls.

You don't need a repo_token to get repo info from the API at /repos, or from the web app. You just need a personal access token for /repos or http auth for the web app.

---

Re: issues/1189, I think private vs public repos is not the limitation people are facing there. The limitation is that you can't GET the coverage data through the API, only through the web app. It is a limitation. That's why some users have resorted to scripts like this one posted by this user.

[LukeGuanY]

Hi @afinetooth, thank you so much for the answer.

The /repos endpoint of the API does not provide the coverage data. I believe that getting the coverage data from the API endpoints is a very demanding and basic feature. Please consider implementing this feature. Thank you.

[afinetooth]

Hi @LukeGuanY I agree. I submitted a feature request.

I'll update this issue when it's delivered, but feel free to email support@coveralls.io for status and reference this issue.

Thank you!

[tperryba]

I have the same requirement, works fine in a browser, but can't authenticate via an rest call from an outside source.

[tperryba]

@afinetooth Any estimated timeline on this feature request?

[afinetooth]

Hi @tperrycb replied to your email support request.

Right now, no update on the feature request but I have +1'd it for you.

[ivailop]

We need the same rest API access to coverage details for a commit or a branch of a private repo.

@afinetooth, sorry but it is not clear, is that private functionality broken or just never existed? Could you please clarify?

[afinetooth]

@ivailop never existed. The original feature created for sharing coverage stats outside of Coveralls is the Notifications feature in Repo Home > Settings > Notifications.

You can send notifications through Slack, Email, etc. The one most people use in the generic Webhook Notification, which sends JSON:

Example:

Example output:

{
  "created_at": "2020-08-07T01:15:26Z"
  "url": ""
  "commit_message": "Update README.md"
  "branch": "travis"
  "committer_name": "GitHub"
  "committer_email": "noreply@github.com"
  "commit_sha": "1a25098fcb26dacc8b549274b2194f2ae4eb4024"
  "repo_name": "afinetooth/coveralls-demo-ruby"
  "badge_url": "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_100.svg"
  "coverage_change": "0.0"
  "covered_percent": "100.0"
}

[jminuscula]

@afinetooth thank you for the workarounds,

we're trying to fetch coverage numbers for data analysis purposes. We have hundreds of repos, and new ones are created every week. We could build a service to process the webhook call, but if we need to manage the notifications manually this won't scale for us.

+1 to making coverage information available through the API.

Thank you!

[afinetooth]

Thanks @jminuscula. Totally understand that. Have +1'd you / updated the feature card in our backlog.

[zhorvatic]

The same use-case for us as well. We have hundreds of repos, so having it in API would be great.

A list response with registered org repos and coverage for a specific branch requested would be awesome.

[LasseRafn]

Definitively would like to see this.

[afinetooth]

Hi, @LasseRafn.

Thanks for the +1.

We're experiencing an extremely high volume of support requests this week and are working through a backlog. We'll respond to your issue more in full if necessary as soon as we possibly can.

In the meantime, I wanted to share a workaround that works for some customers, which is to use the badge URL and grep out the current coverage %.

You can get the badge URL from your Coveralls repo page and you can filter it by branch. Something like this:

https://coveralls.io/repos/github/afinetooth/coveralls-demo-ruby-enterprise/badge.svg?branch=main

Clicking the EMBED button will show markup containing the URL.

Calling that URL should return another URL in a form like:

badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_80.svg"

So if you split the response by /, ., and then _ and get the value at [1] in the remaining array, you should have the coverage %.

Thanks.

[sevindi]

Hi, @LasseRafn.

Thanks for the +1.

We're experiencing an extremely high volume of support requests this week and are working through a backlog. We'll respond to your issue more in full if necessary as soon as we possibly can.

In the meantime, I wanted to share a workaround that works for some customers, which is to use the badge URL and grep out the current coverage %.

You can get the badge URL from your Coveralls repo page and you can filter it by branch. Something like this:

https://coveralls.io/repos/github/afinetooth/coveralls-demo-ruby-enterprise/badge.svg?branch=main

Clicking the EMBED button will show markup containing the URL.

Calling that URL should return another URL in a form like:

badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_80.svg"

So if you split the response by /, ., and then _ and get the value at [1] in the remaining array, you should have the coverage %.

Thanks.

But this still would need cookie header, since we are not able to get that with auth token.

[afinetooth]

Hello @LukeGuanY @tperryba @ivailop @jminuscula @zhorvatic @LasseRafn

I'm happy to share that we've made more coverage data available via the API. I hope "better late than never" applies here for most if not all of you, and your use cases.

Let me share the details on the coverage data, and the particulars on how to get this data via the API. There was a distinction here that I failed to understand and share earlier when I was not as familiar with how our JSON data is available both through our API and our Web app:

Coverage data

In addition to covered_percent and coverage_change, we now share the following data for any Repo or any Build on Coveralls:

• covered_lines
• missed_lines
• relevant_lines
• covered_branches
• missed_branches
• relevant_branches

Example

From our public repo for our official integration, the Coveralls Universal Coverage Reporter: https://coveralls.io/github/coverallsapp/coverage-reporter

Repo: JSON data view:

Just add .json to the repo URL: https://coveralls.io/github/coverallsapp/coverage-reporter.json

By default, the repo's last build is shown:

{
  repo_name: "coverallsapp/coverage-reporter",
  branch: "ci/add-windows-tests",
  url: "https://github.com/coverallsapp/coverage-reporter/actions/runs/5658723971",
  badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_94.svg",
  created_at: "2023-07-25T15:28:26Z",
  commit_message: "Merge 8968731d0be892d19e78cdc9d87d2cce3c651c6a into 87483c10a69f64521d18cc58e63c29e8988702f1",
  committer_name: "GitHub",
  committer_email: "noreply@github.com",
  commit_sha: "2b50da293649d5826a61f505b58331b5366c7f88",
  coverage_change: 0,
  covered_percent: 93.56846473029046,
  covered_lines: 902,
  missed_lines: 62,
  relevant_lines: 964,
  covered_branches: 0,
  missed_branches: 0,
  relevant_branches: 0
}

With paging: Use .json with ?page=<page_number>: https://coveralls.io/github/coverallsapp/coverage-reporter.json?page=1

All builds shown in reverse cron order:

{
  page: 1,
  pages: 24,
  total: 235,
  builds: [
  {
    repo_name: "coverallsapp/coverage-reporter",
    branch: "ci/add-windows-tests",
    url: "https://github.com/coverallsapp/coverage-reporter/actions/runs/5658723971",
    badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_94.svg",
    created_at: "2023-07-25T15:28:26Z",
    commit_message: "Merge 8968731d0be892d19e78cdc9d87d2cce3c651c6a into 87483c10a69f64521d18cc58e63c29e8988702f1",
    committer_name: "GitHub",
    committer_email: "noreply@github.com",
    commit_sha: "2b50da293649d5826a61f505b58331b5366c7f88",
    coverage_change: 0,
    covered_percent: 93.56846473029046,
    covered_lines: 902,
    missed_lines: 62,
    relevant_lines: 964,
    covered_branches: 0,
    missed_branches: 0,
    relevant_branches: 0
  },
  {
    repo_name: "coverallsapp/coverage-reporter",
    branch: "ci/add-windows-tests",
    url: "https://github.com/coverallsapp/coverage-reporter/actions/runs/5658600841",
    badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_94.svg",
    created_at: "2023-07-25T15:17:52Z",
    commit_message: "Merge 70887d69c078df1006270b47a39622042d490472 into 87483c10a69f64521d18cc58e63c29e8988702f1",
    committer_name: "GitHub",
    committer_email: "noreply@github.com",
    commit_sha: "660ce3b7e5e39210cdb9dedb4faabfd837c284a9",
    coverage_change: 0,
    covered_percent: 93.56846473029046,
    covered_lines: 902,
    missed_lines: 62,
    relevant_lines: 964,
    covered_branches: 0,
    missed_branches: 0,
    relevant_branches: 0
  },
  [...]
 ]
}

Repo: JSON data by branch:

Use .json with ?branch=<branch_name>: https://coveralls.io/github/coverallsapp/coverage-reporter.json?branch=master

By default, the last build on branch is shown:

{
  repo_name: "coverallsapp/coverage-reporter",
  branch: "master",
  url: "https://github.com/coverallsapp/coverage-reporter/actions/runs/5585273079",
  badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_94.svg",
  created_at: "2023-07-18T08:47:54Z",
  commit_message: "0.6.4: improve LCOV parsing speed",
  committer_name: "Valentin Kiselev",
  committer_email: "mrexox@evilmartians.com",
  commit_sha: "87483c10a69f64521d18cc58e63c29e8988702f1",
  coverage_change: 0,
  covered_percent: 93.56846473029046,
  covered_lines: 902,
  missed_lines: 62,
  relevant_lines: 964,
  covered_branches: 0,
  missed_branches: 0,
  relevant_branches: 0
}

With paging: Use .json with ?branch=<branch_name> and &page=<page_number>: https://coveralls.io/github/coverallsapp/coverage-reporter.json?branch=master&page=1

All branch builds shown in reverse cron order:

{
  page: 1,
  pages: 9,
  total: 90,
  builds: [
  {
    repo_name: "coverallsapp/coverage-reporter",
    branch: "master",
    url: "https://github.com/coverallsapp/coverage-reporter/actions/runs/5585273079",
    badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_94.svg",
    created_at: "2023-07-18T08:47:54Z",
    commit_message: "0.6.4: improve LCOV parsing speed",
    committer_name: "Valentin Kiselev",
    committer_email: "mrexox@evilmartians.com",
    commit_sha: "87483c10a69f64521d18cc58e63c29e8988702f1",
    coverage_change: 0,
    covered_percent: 93.56846473029046,
    covered_lines: 902,
    missed_lines: 62,
    relevant_lines: 964,
    covered_branches: 0,
    missed_branches: 0,
    relevant_branches: 0
  },
  {
    repo_name: "coverallsapp/coverage-reporter",
    branch: "master",
    url: "https://github.com/coverallsapp/coverage-reporter/actions/runs/5585239014",
    badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_94.svg",
    created_at: "2023-07-18T08:43:02Z",
    commit_message: "fix: optimize lcov parser (#95)",
    committer_name: "GitHub",
    committer_email: "noreply@github.com",
    commit_sha: "1f55ca4a6e13fa34725b45108a09425a5d5b51be",
    coverage_change: 0.01,
    covered_percent: 93.56846473029046,
    covered_lines: 902,
    missed_lines: 62,
    relevant_lines: 964,
    covered_branches: 0,
    missed_branches: 0,
    relevant_branches: 0
  },
  [...]
 ]
}

Build: JSON Data

Same pattern as above. Just add .json to the regular Web URL: https://coveralls.io/builds/61406487.json

But since builds are single entities, each on one branch, the branch (?branch=<branch_name>) and paging (?page=<page_number?) parameters don't have a place here.

{
  repo_name: "coverallsapp/coverage-reporter",
  branch: "fix/optimize-lcov-parser",
  url: "https://github.com/coverallsapp/coverage-reporter/actions/runs/5584938573",
  badge_url: "https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_94.svg",
  created_at: "2023-07-18T08:13:02Z",
  commit_message: "Merge 6a860a26341dc9654bbe14a294c6b9662be2dae7 into 407eecfe486c670b03fae509fe79c73183394756",
  committer_name: "GitHub",
  committer_email: "noreply@github.com",
  commit_sha: "0af2c5ca81de7df8a3fdee28fd471ed1605a2644",
  coverage_change: 0.01,
  covered_percent: 93.56846473029046,
  covered_lines: 902,
  missed_lines: 62,
  relevant_lines: 964,
  covered_branches: 0,
  missed_branches: 0,
  relevant_branches: 0
}

How to use the data

As you please, but In case you are not familiar with how the coverage data applies to our aggregate coverage formula, here that is:

Aggregate coverage formulae

Aggregate coverage with branch coverage enabled:

aggregate_coverage w/ branches = (covered_lines + covered_branches) / (relevant_lines + relevant_branches)

Aggregate coverage without branch coverage enabled (in repo settings):

aggregate_coverage w/o branches = covered_lines / relevant_lines

Given the above, you can extrapolate how to use missed_lines and missed_branches, which are not used in the above formulae, to derive additional coverage info, like the inverse of "covered %," which you might call "missed %," etc, or to determine changes in any data point between any two builds in a given repo, or between the latest builds in two different repos for that matter.

Accessing the coverage data:

You can get the data via the Coveralls Web app UI, by simply adding .json to the ends of normal Web URLs, or via the Coveralls API.

The key to accessing the same JSON data via the API is to use the repo's Repo Token in the API request, as follows:

Example

cURL example: Make the request to the normal Web URL with .json extension (and/or other URL params as shown above), but simply add the Coveralls Repo Token for your repo, as repo_token=<repo_token>:

curl --location 'https://coveralls.io/github/coverallsapp/coverage-reporter.json?repo_token=toK5M7Ee5DoXgC4IpmKCTlaaU9KNYRnVL'

To clarify, the Personal Access Token (PAT) required for some API requests is not required for this data. Only the Coveralls Repo Token for your repo.

I'll stop there. Please let me know if I can make this answer better for you.