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:

  • 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 WebHooks 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.

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"}

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.

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