Subscribing to Workloads

Once you’ve successfully created your project in Expeditor, the next step is subscribe to workloads. Like IFTTT, Expeditor allow you to trigger actions when events occurs in integrated systems. For example:

If Then
A GitHub pull request is merged Bump the version of our software, update the CHANGELOG.md, and trigger a new artifact build.
An artifact is successfully uploaded to Artifactory Trigger a job in our deploy pipeline to deploy that artifact to our dev/test environment.
A new version of an upstream dependency is uploaded Trigger a new build of our software that automatically pulls in that new version.

When Expeditor receives an event from an integrated system, it processes the payload associated with that event into a workload and publishes that workload out to subscribed agents. Agents can define which Workloads they would like to react to by specifying the appropriate subscription, and associating an action set that should be executed when that workload is received.

Composition of a Subscription

A subscription is comprised of two pieces: a workload ID glob (workload) and an action set (actions).

subscriptions:
  - workload: pull_request_merged:{{agent_id}}:*
    actions:
      - noop:action_one
      - noop:action_two

The workload ID glob is comprised of two pieces: the event and the event ID glob. In the example above, pull_request_merged is the event and {{agent_id}}:* is the event ID glob (see below for details on subscription template variables).

subscriptions:
  - workload: "<EVENT>:<EVENT_ID_GLOB>"
    actions:
      <ACTION_SET>

For a full list of events, and a description of how to use event ID globs, check out the workloads reference documentation.

Subscriptions Keyword

The power of the subscriptions keyword is that you can subscribe to any workload published within Expeditor, even workloads not associated with your project. This allows you to not only react to events associated with your own software project, but other software projects as well. Depending on the currently enabled integrated systems, you may even be able to react to events outside of your organization entirely.

For a detailed list of all the available workloads you can subscribe to, check out the workloads reference documentation.

Subscription Template Variables

In projects with complex subscriptions, it can be cumbersome and/or confusing to frequently reference certain values over and over again. To assist with this, Expeditor provides templating variables that can provide clarity to your subscriptions while also making it easier to manage some values that may change regularly.

Variable Value Example
{{agent_id}} The name of your Expeditor project. chef/example:master
{{github_repo}} The name of your GitHub repository. chef/example
{{release_branch}} The name of your release branch. master
{{version_constraint}} The version constraint associated with the current release branch. *
Example for chef/example:master using variables
---
github:
  release_branch:
    - master:
        version_constraint: 2.*
    - legacy:
        version_constraint: 1.*

subscriptions:
  # equivalent to 'artifact_published:stable:chef:2.*'
  - workload: artifact_published:stable:chef:{{version_constraint}}
    actions:
      - noop:some_action
  # equivalent to 'pull_request_merged:chef/example:master:*'
  - workload: pull_request_merged:{{agent_id}}:*
    actions:
      - noop:some_other_action

Scheduling Workloads

In addition to subscribing to events from external sources such as GitHub webhook notifications or Slack slash commands, it is possible to subscribe to workloads that are triggered on a specified schedule. Interacting with scheduled workloads involves two components: the schedule and the subscription.

Schedules are defined per-project in your .expeditor/config.yml and consist of an all lowercase name (in snake case), a description, and a Fugit compatible cronline.

---
schedules:
  - name: sample_schedule
    description: A sample schedule
    cronline: "0 0 * * *"

At the time associated with the cronline, a special schedule workload is triggered using the schedule_triggered event. You can subscribe to this workload and specify an action set that should be executed.

---
schedules:
  - name: sample_schedule
    description: A sample schedule
    cronline: "0 0 * * *"

subscriptions:
  - workload: schedule_triggered:{{agent_id}}:sample_schedule:*
    actions:
      - noop:sample_schedule_action