CircleCI Integration

Overview

The following example demonstrates how to trigger a CircleCI build for a Github project using a CUSTOM webhook in the ATSD rule engine.

The integration relies on the Circle CI API new-build-branch method for triggering a new build of the specified branch.

Configuration

Create a new CUSTOM webhook from scratch or import the following template, used in this example. To import an XML template file, open Alerts > Outgoing Webhooks, select Import in the split button located below the table and follow the prompts.

To create a new notification, open Alerts > Outgoing Webhooks and click Create.

Parameters

Enter a name and specify the following parameters:

Name Value
Method POST
Content Type application/json
Authentication Basic
Username <CIRCLE_USER_TOKEN>
Endpoint URL https://circleci.com/api/v1.1/project/github/<GITHUB_USER>/${project_name}/tree/${branch}
Headers Accept: application/json

Modify the Endpoint URL by replacing the <GITHUB_USER> field with your GitHub user name.

The Endpoint URL may look as follows: https://circleci.com/api/v1.1/project/github/axibase/${project_name}/tree/${branch}

Enter the Circle CI user token into the Username field but leave the Password field empty.

Keep the ${project_name} and ${branch} placeholders in the URL path so that they may be customized in the rule editor. This allows you to trigger builds for different projects using the same webhook.

Payload

The webhook can be configured to send a JSON document to the Circle CI endpoint to pass extended build parameters and the Body field can include the following text:

{
  "parallel": "${parallel}",
  "build_parameters": {
    "RUN_EXTRA_TESTS": "${run_extra_tests}",
    "timezone": "${timezone}"
  }
}

Make sure that you enclose fields with double quotes, if necessary.

Leave the Body field empty for non-parameterized projects.

Rule

Create a new rule or import the rule template used in this example. To import an XML template file, open the Alerts > Rules page, select Import in the split button located below the table and follow the prompts.

To create a new rule, open the page Alerts > Rules and click Create.

Specify the key settings on the Overview tab.

Name Value
Status Enabled
Metric test_m
Condition value > 1

Open the Webhooks tab.

Set Enabled to Yes and choose the previously created webhook from the Endpoint drop-down.

Enable Open and Repeat triggers. Set the Repeat Interval to All.

Specify the same settings for the Open and Repeat triggers:

Name Value
branch master
parallel 4
project_name atsd-api-java
run_extra_tests false
timezone Etc/UTC

Note that these parameters are visible in the rule editor because their placeholders are present in the Endpoint URL and JSON payload.

When the notification is executed, all placeholders in the request URL and the payload is resolved as follows:

https://circleci.com/api/v1.1/project/github/axibase/atsd-api-java/tree/master

{
  "parallel": "4",
  "build_parameters": {
    "RUN_EXTRA_TESTS": "false",
    "timezone": "Etc/UTC"
  }
}

If the placeholder is not found, the placeholder is replaced with an empty string.

Test

Test the integration by submitting a sample series command on the Data > Data Entry page.

  series e:test_e m:test_m=2

The value causes the condition to evaluate to true, which in turn triggers the notification. To verify that an alert was raised, open the page Alerts > Open Alerts and check that an alert for the test_m metric is present in the Alerts table.

Check the CircleCI user interface to make sure the target build was triggered.