Notifications

Solano CI supports flexible integration with email, many common group collaboration tools, polling status tools like CCMenu, and API integrations via outgoing webhooks.

Note

We are migrating notification configuration from a UI-oriented system to a rule-based configuration controlled centrally in your solano.yml file. This documentation reflects the solano.yml approach. For details on the old system, see UI-Based Configuration.

If you configure solano.yml notifications, they will take precedence over UI-configured notifications. As we refine the rule-based configuration, we welcome your feedback and your bug reports to support@solanolabs.com.

Notifications associated with builds are configured using rules written in your solano.yml file.

A notification rule uses filters to match against build attributes to control sending a notification on a channel using configuration parameters.

Let’s start with an example and then work through the concepts and options:

notify:
- channel: email
  trigger-on: failed
  branch: feature/*
  message: "Congratulations, testing of %repo%'s %branch% branch finished in %duration% with %error-count% error(s) and %passed-count% success(es)"
  recipients: committers

- channel: hipchat
  trigger-on: status-changed
  branch: master
  room: developers
  message: "@releasemanager Congratulations, testing of %repo%'s %branch% branch finished in %duration% with %error-count% error(s) and %passed-count% success(es)"

This configuration has 2 rules.

The first rule will send an email whenever a build fails on a branch matching feature/* to the users whose commits were included in the build, with a subject that identifies the repo, branch, duration and counts of errors and passed tests.

The second rule will send a hipchat message to the developers room whenever the status of the master branch changes (e.g., passed to failed, failed to passed, etc.) that tags the @releasemanager user.

Rule Evaluation

At lifecycle events in a build, the notification rules will be evaluated in order. All rules that match on all of their filter criteria will trigger a notification.

Channels

Every notification rule must have a single channel key that identifies which channel will be notified if the filter keys match. The following values are supported for channel:

  • email
  • slack
  • hipchat
  • campfire
  • flowdock

Filters

Notification rules support filtering on a few different parameters:

  • trigger-on: Build lifecycle event on which to trigger the notification (default: done).
    • Options: start|first-fail|done|{status}|status-changed|{laststatus}-to-{thisstatus}
    • status, laststatus, thisstatus is one of: notstarted, started, passed, failed, pending, skipped, error
  • org | organization: Solano organization name (default: no restriction)
    • For a repo thats connected to multiple organizations, this filter allows for per-organization control
  • branch: Branch pattern (default: *)
    • include/exclude rule list: by default entries are include rules. include rules can be prefixed with “+” exclude rules should be prefixed with “-”. Rules are evaluated in order, with the first match being final.
    • lists of rules must be written as YAML lists, not comma separated lists
    • Either: - a glob or list of globs (e.g. *a* or wip-*) - regex or list of regexes (e.g. /a/ or /wip-.*/)
notify:
- channel: email
  trigger-on: failed
  branch:
    - feature/*
    - hotfix/*
  message: "Congratulations, testing of %repo%'s %branch% branch finished"
  recipients: committers

Common Parameters

  • recipients: Email recipients (default: admins)
    • Email address, or list of email addresses
    • committers: substituted for the committers in the build
    • admins: substituted for the owners and admins of the Solano organization where the build ran
    • owners: substituted for the owners of the Solano organization where the build ran
    • everyone: substituted for all members of the Solano organization where the build ran

Note that when processing substitutions, only users who have not disabled e-mail notification will be included.

  • image: Image to attach to the message (optional)
    • Image URL or list of URLs
    • If multiple URLs are specified, one is chosen at random
  • message or subject: The short message or Email subject line (default: builtin subject)
  • body: Email body (default: builtin body)
    • String with template substituted variables

Channel-specific Parameters

  • room: Hipchat/Campfire room, Slack Channel
    • Required for rules with channel set to one of (hipchat, campfire, slack)
  • loud: Use a loud HipChat notification (default: false)
  • team: Slack Team, required for rules with channel set to slack
  • subdomain: Campfire subdomain, required for rules with channel set to campfire
  • flowdock: Flowdock specific options
    • Hash accepting these keys:
      • application-id: string (optional)
      • team-chat: boolean (default: true)
      • team-inbox: boolean (default: true)

Template Variables

Notification rules allow variable expansion in the message (or subject) and body parameters. You can insert a variable by surrounding it with % s. For example, %repo% will insert the name of the repository for the build.

Message Variables

The following variables will be expanded in the message or subject parameters:

  • org: The name of the Solano CI organization
  • repo: The name of the current build’s repository
  • branch: The name of the current build’s branch
  • start-time: Build start time, as a UTC string
  • end-time: Build end time, as a UTC string
  • duration: Build duration in seconds
  • status: Current build status
  • {status}-count: The count of tests that completed with status {status} (notstarted, started, passed, failed, pending, skipped, error); for instance, write: passed-count
  • {status}-name-list: The list of test names that completed with status {status}.
  • commit: The commit ID of the latest commit in this build
  • committer: The email address of the latest committer in this build
  • commit-message: The latest commit message in this build
  • profile-name: The name of the profile run
  • build-id: The identifier for the build
  • build-url: A URL pointing to the build report page
  • image: A random image URL taken from the currently matching notification rule; for e-mail channels user should wrap in explicit img tag

Additional Body Variables

All of the variables allowed in the message parameter are allowed in the body parameter.

The following additional variables are allowed:

  • default-email-body: The complete default email body template.

Adding Markup to Default Email (%default-email-body%)

You can add custom markup to the default email body that Solano CI generates.

For example, if you want to add a set of links to your deploy tool and self-hosted SCM, you can use HTML in the body override and then template in the entire default body.

notify:
- channel: email
  body: '
  <ul>
  <li><a href="https://scm.company.com/%repo%/commits/%commit%">View Commit</a></li>
  <li><a href="https://deploytool.company.com/builds/%build-id%">View Deploy</a><li>
  </ul>
  %default-email-body%
  '

Note that you will have to use inline CSS styles for further changes to layout in order to be compatible with most web-based email clients, such as Google Apps.

UI-Based Configuration

Note

UI-based configuration is being phased out in favor of the above described rule-based configuration in solano.yml. solano.yml notification configuration will take precedence over UI-based configuration.

Campfire, Flowdock, HipChat, and Slack Notifications

Solano CI can send build notifications directly to your Campfire, FlowDock, HipChat, or Slack instance.

  • Visit your organizations list and sign in.
  • Navigate to the configuration for the proper organization
  • Click on “Chat Notifications”
  • Fill in your Campfire Subdomain, Token and Room; your HipChat token and Room; your Flowdock inbox; or your Slack Team, Channel, and Token to set it up.
  • Click “Save Changes”
  • Test your chat notification by pressing the green “Test” button

If you have trouble with HipChat notifications, you may wish to test your room and token with the curl command line utility. HipChat documentation on generating and testing tokens is available on the HipChat website. You will want to use the HipChat v1 API key.

Email Notifications

If you have configured Solano CI to notify HipChat or Campfire for your projects, you may want to disable email build notifications entirely. To do so, follow these steps:

  • Visit your user profile page.
  • Click on “Notifications”
  • Uncheck and click Save Changes to disable your personal e-mail notifications

You will continue to receive administrative emails and newsletter updates from Solano CI. Disabling email notifications does not impact other notifications or any other permissions in Solano CI.

All build emails contain a link to let you manage your notification settings. You can also reach the notification page from the your user profile page.

If you want to set finer-grained control of e-mail notifications on an organization-wide basis, follow these steps instead:

  • Visit your organizations list and sign in.
  • Navigate to the configuration for the proper organization
  • Uncheck the box marked “Uncheck to disable all build notifications”
  • Add or remove rules to control notifications as a function user, role, and branch.

Pull Notifications

You can subscribe to pull notifications using the CCMenu endpoint. You can retrieve the URL for the CCMenu endpoint by going to your organization’s configuration page and clicking on “CC Menu (XML Status)”. The organization configuration page is accessible via the “Organizations” menu item in the menu in the upper right hand corner of the web UI.

The URL for the CCMenu endpoint has an endpoint-specific API key embedded in it, so treat the URL with care. The API key can be regenerated along with all other API keys upon request.

Other Notifications

You can also implement notifications of your own using a post-build hook. The post-build hook runs after the entire build is complete and provides the status of both the previous and current build. You can run a notification script as well as automatically deploy your repository to a staging or production environment. We’ve published a simple Campfire notifier that replicates the built-in Campfire functionality in Solano CI as a gist here: https://gist.github.com/2254756. Check in the notification script as bin/campfire.rb in your repository, add the tinder gem to the test group in your Gemfile, and add a post build hook that invokes the script.

You can configure the sample notifier by setting the following config variables for your repository:

  1. CAMPFIRE_DOMAIN
  2. CAMPFIRE_ROOM
  3. CAMPFIRE_TOKEN