Web Hooks

Solano CI supports webhooks, both incoming to trigger builds and outgoing to notify external services of build start and stop.

Build Trigger Webhooks (Incoming)

Each repository configured in Solano CI has a unique incoming webhook URL that accepts a variety of POST payload formats.

You can find the webhook URL for initiating a build in CI (and the SSH pull key associated with the Repo) in your Solano CI Dashboard:

  1. Click on the gear icon next to the repository you wish to configure
  2. Select CI Setup.
  3. The post commit webhook URL is displayed under POST-COMMIT WEBHOOK URL. Note that the full URL contains an embedded authentication token as the last component of the URL path.

Note

Full support for some hosting providers requires using a provider specific endpoint. The default endpoint is /1/builds/<KEY>. The provider specific endpoint is /1/github/<KEY>, /1/stash/<KEY>, etc. If in doubt, use /1/builds/<KEY>.

Our generic format is to accept an HTTPS POST with Content-Type: application/json and the following POST body format:

{"source": "solano",
 "op": "push",
 "force": true,
 "queue_position": "tail",
 "scm": "<OPTIONAL - git or hg>",
 "head": "<OPTIONAL - commit id to build>",
 "branch": "<OPTIONAL - branch name, default to master>",
 "ref": "<OPTIONAL - private ref/head for this build>",
 "profile_name": "<OPTIONAL - profile name to use>",
 "refspec": ["<OPTIONAL - array of git refspecs to pull from scm>"],
 "changeset": {"kind": "<KIND>",
               "id": "<PR ID>",
               "url": "<LINK TO DISPLAY>"},
 "env": "<OPTIONAL - object of environment variables>"}

Field reference:

  • The source field must be present and the value must be the string "solano".
  • Set force to false to only build if there have been new commits since the last build.
  • Set scm to git or hg; if empty, git will be assumed.
  • Set branch to specify the branch; the default branch is master.
  • Set head if you want to build a specific commit from the upstream repo; defaults to HEAD for git and tip for merurial.
  • Set profile_name if you want to force the build to run with a specific single profile, overriding the default behavior of running the default profile or triggering the configured build plan.
  • Set refspec to an array of git refspecs to control what Solano CI pulls from your SCM.
  • Set changeset describe a pull request or changeset e.g. from Github, Gerrit, Phabricator, etc. The kind is currently one of github, gerrit, phabricator, or generic. The id field is the changeset ID and the url is the URL to display in the report page.
  • Set env to pass environment variables. Example: {"env": {"PATH": "/home", ...}}
  • Set queue to overide the queue a build will run on. see Custom Queues for more info

The response will have the format:

{"status": 0,
 "guid": "c946783126c9e74291d24465f0a60",
 "status_uri": "https://ci.solanolabs.com/ci_events/c946783126c9e74291d24465f0a60/guid"}

Examples with curl:

curl -H 'Content-type: application/json' \
     -d '{"source": "solano", "branch": "unstable", "force": true}' \
     https://hooks.solanolabs.com/1/builds/2390812089347102894710897241089274

If you get a 404 response, please check that you are using the correct, complete URL. For product-specific integrations (e.g. Github, Stash), see Build Trigger WebHook Integrations.

Build Notification Web Hooks (Outgoing)

Web hooks to notify your systems about Solano CI build events may be configured and installed on a per-organization basis.

To configure a new outbound webhook or remove an existing one:

  1. Go to your Organizations page.
  2. Click on Web Hooks in the menu.
  3. Enter a URL where Solano will send a POST. The URL should be either an HTTP or HTTPS URL. If the URL is an HTTPS URL and the remote server’s certificate is not signed by a well-known CA, the hook will be dropped. Please contact support if this poses a problem for you.
  4. (optional) You may specify a HTTP basic auth username & password that will be sent alongside the POST

Solano CI will post a JSON payload to your webhook URL. An example a payload is shown below.

{"event":"test",
 "timestamp": "2015-08-25T00:58:27Z", # optional event timestamp
 "session":351279,
 "guid":"c946783126c9e74291d24465f0a60",
 "url":"https://ci.solanolabs.com/1/reports/351279",
 "parent_session":351278,             # parent session IF multi session plan
 "profile_name":"default",            # name of profile run by session
 "commit_id":"38d4d2548e85729e138fdba32e08421bb899ba37",
 "committers":[],                     # list of committers participating
 "status":"passed",
 "counts":{"notstarted":0,
           "started":0,
           "passed":234.0,
           "failed":0.0,
           "pending":3.0,
           "skipped":0.0,
           "error":0.0},
 "workers":24,
 "stopped_by":"user@mycompany.com",          # for manually stopped sessions

 # build timing data is stored in the "timing" sub-hash
 # NB: may not reflect queue delay if queue is re-ordered
 # Each event in the build lifecycle is labeled by the key and timestampped by the value
 # See list of additional advanced events below
 "timing":{
   "ci_received_at": 1475250402.480408,
   "queue_first_seen_at": 1475250412.841408,
   "queue_first_allowed_at": 1475250492.863428,
   "workers_assigned_at": 1475250493.136248
 },
 "branch":"production", "ref":"refs/head/production",
 "repository":{"name":"repo_name",
               "url":"ssh://git@github.com/organization_name/repo_name",
               "org_name":"organization_name"},
 "xid":"372da4f69"}

Web Hook Closures (Outgoing)

Solano CI can also optionally transform the JSON payload to allow better integration with third-party systems. Web Hook Closures are written in javascript, and will be run every time an event is sent. The payload variable will contain the json payload in the format listed above.

function transform_payload(payload) {
  // Transformation code belongs here
  var headers = {"content-type": "application/json"};

  var body = [{"eventType": payload["event"],
               "timestamp": Date.parse(payload["timestamp"]),
               "session_id": payload["session"]}];

  return {'status': 'ok', 'headers': headers, 'body': body};
}

Web Hook Closures can be edited in the Web Hook UI under your Organization’s page.

Web Hook Events (Outgoing)

Solano CI will notify on 5 build lifecycle events:

  1. received - the API call or SCM webhook to trigger this build was received
  2. start - the build has started work on a Solano worker
  3. test - the build has completed its compile or setup process and has started running tests
  4. first-fail - the first test failure
  5. stop - the build has completed, either naturally or after being stopped by a user

Solano CI will employ limited retry of connection and low-level HTTP errors; use the xid parameter in the posted JSON for idempotency. Stopped builds will include the handle or email address of the user who stopped the build. For debugging, a log of all attempted outbound webhook events is listed on the Organization’s Web Hook settings page.

Advanced Timing Data

The following build lifecycle events are recorded in the timing section of a webhook event, when appropriate. Per the example above, these are in addition to the timestamps documented in the sample payload above. In order they are:

  • setup
  • package_setup
  • services_setup
  • package_setup
  • setup_hooks
  • worker_hooks
  • exec
  • post_build
  • artifact_collect
  • done
  • setup_post_hooks
  • capture_cache
  • setup_cache
  • worker_rendezvous
  • post_build_hook