Get Started

Integrating with Coveralls

Coveralls Builds

The Web App

The API

Get Help

API > The /Repos Endpoint

api-cry

Overview

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:

  • Resource: Coveralls Repository (repo)
  • Actions: POST (Create) / GET (Read) / PUT (Update) / DELETE (Delete)
  • URI: https://coveralls.io/api/v1/repos *
  • Data format: JSON
  • Authentication: Personal API Token

    * If using Coveralls Enterprise, replace coveralls.io with the hostname of your instance.

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.

Authentication

Personal API Tokens

Requests to the /repos endpoint are authenticated using Personal API Tokens, which can be obtained on your Coveralls Account Page:

account-personal-api-token

The “Authorization” header is used to send this token, in the format “token XXX” where XXX is replaced with your token:

Example Authorization Header

Accept: application/json
Content-Type: application/json
Authorization: token RGVsaXZlciUyMGJldHRlciUyMGNvZGUu

Create a New Repo at Coveralls

Endpoint

POST /api/repos

Parameters

Name Description Type
repo[service] required Git provider. Options include: github, bitbucket, gitlab, stash, manual String
repo[name] required Name of the repo. E.g. with Github, this is username/reponame. String
repo[comment_on_pull_requests] Whether comments should be posted on pull requests (defaults to true) Boolean
repo[send_build_status] Whether build status should be sent to the git provider (defaults to true) Boolean
repo[commit_status_fail_threshold] Minimum coverage that must be present on a build for the build to pass (default is null, meaning any decrease is a failure) Float or null
repo[commit_status_fail_change_threshold] If coverage decreases, the maximum allowed amount of decrease that will be allowed for the build to pass (default is null, meaning that any decrease is a failure) Float or null

Request

Route

POST /api/repos

Headers

Accept: application/json
Content-Type: application/json
Authorization: token RGVsaXZlciUyMGJldHRlciUyMGNvZGUu

Body

{
    "repo": {
        "service": "github",
        "name": "username/reponame",
        "comment_on_pull_requests": false,
        "send_build_status": true,
        "commit_status_fail_threshold": 75.5,
        "commit_status_fail_change_threshold": null
    }
}

Response

Response Fields

Name Description Type
repo[name] Name of the repo String
repo[comment_on_pull_requests] Whether comments will be posted on pull requests Boolean
repo[send_build_status] Whether build status will be sent to the git provider Boolean
repo[commit_status_fail_threshold] Minimum coverage that must be present on a build for the build to pass (null means that any decrease is a failure) Float or null
repo[commit_status_fail_change_threshold] If coverage decreases, the maximum allowed amount of decrease that will be allowed for the build to pass (null means that any decrease is a failure) Float or null
repo[created_at] Timestamp of the creation of this Repo Timestamp
repo[updated_at] Timestamp of the last modification to this Repo Timestamp

Status

201

Headers

Content-Type: application/json; charset=utf-8

Body

{
    "repo": {
        "service": "github",
        "name": "username/reponame",
        "comment_on_pull_requests": false,
        "send_build_status": true,
        "commit_status_fail_threshold": 75.5,
        "commit_status_fail_change_threshold": null,
        "created_at": "2000-01-01T08:00:00Z",
        "updated_at": "2000-01-01T08:00:00Z"
    }
}

Get Repo Info From Coveralls

Endpoint

GET /api/repos/:service/:repo_user/:repo_name

Request

Route

GET /api/repos/github/GithubUser2/repo-1

Headers

Accept: application/json
Content-Type: application/json
Authorization: token RGVsaXZlciUyMGJldHRlciUyMGNvZGUu

Response

Response Fields

Name Description Type
name Name of the repo String
comment_on_pull_requests Whether comments will be posted on pull requests Boolean
send_build_status Whether build status will be sent to the git provider Boolean
commit_status_fail_threshold Minimum coverage that must be present on a build for the build to pass (null means that any decrease is a failure) Float or null
commit_status_fail_change_threshold If coverage decreases, the maximum allowed amount of decrease that will be allowed for the build to pass (null means that any decrease is a failure) Float or null
created_at Timestamp of the creation of this Repo Timestamp
updated_at Timestamp of the last modification to this Repo Timestamp
token Repo Token (only available if you have access) String

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
    "service": "github",
    "name": "GithubUser2/repo-1",
    "comment_on_pull_requests": true,
    "send_build_status": true,
    "commit_status_fail_threshold": 75.5,
    "commit_status_fail_change_threshold": null,
    "created_at": "2000-01-01T08:00:00Z",
    "updated_at": "2000-01-01T08:00:00Z",
    "id": 2,
    "has_badge": false,
    "token": "heiNGAuzaYFuVBBZ53ujChNbPH8cRznDo"
}

Update a Repo at Coveralls

Endpoint

PUT /api/repos/:service/:user_name/:repo_name

Parameters

Name Description Type
service required Git provider. Options include: github, bitbucket, gitlab, stash, manual String
user_name required Username of the repo. E.g. with Github, this is username/reponame. String
repo_name required Repo name. E.g. with Github, this is username/reponame. String
repo[comment_on_pull_requests] Whether comments should be posted on pull requests (defaults to true) Boolean
repo[send_build_status] Whether build status should be sent to the git provider (defaults to true) Boolean
repo[commit_status_fail_threshold] Minimum coverage that must be present on a build for the build to pass (default is null, meaning any decrease is a failure) Float or null
repo[commit_status_fail_change_threshold] If coverage decreases, the maximum allowed amount of decrease that will be allowed for the build to pass (default is null, meaning that any decrease is a failure) Float or null

Request

Route

PUT /api/repos/github/GithubUser3/repo-2

Headers

Accept: application/json
Content-Type: application/json
Authorization: token RGVsaXZlciUyMGJldHRlciUyMGNvZGUu

Body

{
    "repo": {
        "comment_on_pull_requests": false,
        "commit_status_fail_threshold": 75.5,
        "commit_status_fail_change_threshold": null
    }
}

Response

Response Fields

Name Description Type
repo[name] Name of the repo String
repo[comment_on_pull_requests] Whether comments will be posted on pull requests Boolean
repo[use_status] Whether build status will be sent to the git provider Boolean
repo[commit_status_fail_threshold] Minimum coverage that must be present on a build for the build to pass (null means that any decrease is a failure) Float or null
repo[commit_status_fail_change_threshold] If coverage decreases, the maximum allowed amount of decrease that will be allowed for the build to pass (null means that any decrease is a failure) Float or null
repo[created_at] Timestamp of the creation of this Repo Timestamp
repo[updated_at] Timestamp of the last modification to this Repo Timestamp

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "repo": {
    "service": "github",
    "name": "GithubUser3/repo-2",
    "comment_on_pull_requests": false,
    "send_build_status": null,
    "commit_status_fail_threshold": 75.5,
    "commit_status_fail_change_threshold": null,
    "created_at": "2000-01-01T08:00:00Z",
    "updated_at": "2000-01-01T08:00:00Z"
  }
}

 

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