API > Parallel Build Webhook

Overview

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

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

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.

Example Request

Here’s an example POST request to the Parallel Build Webhook:

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
      "payload": {    
          "build_num": "4193273239",    
          "status": "done"    
      }    
  }' \
  'https://coveralls.io/webhook?repo_token=9DhgwUv9YiJjkm6PP4c6DxBgeUiXObJjK&carryforward=borrower-account-webapp'

Let’s break it down:

• curl: The command-line tool we’re using to make the request.
• -X POST: The HTTP method we’re using to make the request.
• -H 'Content-Type: application/json': Header specifying JSON datatype.
• https://coveralls.io/webhook: The URL of the Parallel Build Webhook.
• -d '{"payload":{"build_num":"4193273239","status":"done"}': The JSON data we’re sending with the request (aka. Payload). This is required.
• ?repo_token=9DhgwUv9YiJjkm6PP4c6DxBgeUiXObJjK: The Coveralls Repo Token for the repo we’re closing the build for. This is required.
• &carryforward=borrower,rates,webapp: The Carryforward Flags for the build we’re closing. This is optional.

Data Parameters

There are three (3) required and one (1) optional parameters for the Parallel Build Webhook:

• Payload (build num and status) - required
• Coveralls Repo Token - required
• Carryforward Flags - optional

Payload (Required)

The Payload JSON object—passed as payload—is required and must have the following properties:

{
    "payload": {
        "build_num": "4193273239",
        "status": "done"
    }
}

Coveralls Repo Token (Required)

The Coveralls Repo Token—passed as the repo_token URL parameter—is required to authenticate the request.

?repo_token=9DhgwUv9YiJjkm6PP4c6DxBgeUiXObJjK

Read more about the Coveralls Repo Token.

Carryforward Flags (Optional)

Carryforward Flags are optional and, when passed as the value for carryforward, can be used to instruct Coveralls to carry forward coverage report data from a previous build for any jobs that are missing from the current build.

?carryforward='subproject_1,subproject_2,subproject_3'

Read more about Carryforward Flags.

All Parameters

Response

200 Success

Coveralls will respond with an HTTP 200 OK response if the request was successful, along with a JSON object containing "done":true, the URL to the finished build—and the number of jobs in it—at Coveralls.

Example

Header: 200 OK
Body: {"done":true,"url":"https://coveralls.io/builds/57681370","jobs":6}

Failure

Any other response code should be considered a failure and the response body will be set to the error text.

Example

Header: 422 Unprocessable Entity
Body: {"error":"No build matching CI build number found"}

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