Workloads

Workload ID

The workload ID is the slug used to uniquely identify a workload within Expeditor. It is comprised of the event and some unique information about that event referred to as the event ID. Here is an example:

                            Workload ID
⊢--------------------------------^----------------------------------------⊣
       Event                             Event ID
⊢--------^--------⊣⊢------------------------^-----------------------------⊣
pull_request_merged:chef/chef:master:97:007ae5d5-2b1f-45a6-810e-ba2390956928

To allow you to subscribe to a class of workload like “all pull requests for chef/chef:master”, subscriptions allow you to use glob patterns in your subscription.

subscriptions:
  # Subscribe to all merged Pull Requests against your GitHub repository
  - workload: pull_request_merged:{{agent_id}}*
    actions:
      - noop:sample_action

  # Subscribe to all chef artifacts published to current
  - workload: artifact_published:current:chef:*
    actions:
      - noop:sample_action

  # Subscribe to all chef 14 artifacts published to current
  - workload: artifact_published:current:chef:14*
    actions:
      - noop:sample_action

Composite Workloads

A composite workload is a workload that, in addition to representing an external event, reference some number of other workloads and represent their interests during execution. The behavior of some actions and action filters will vary based on whether or not they are evaluating a composite workload. For example, exclusive action filters are not supported by composite workloads because it is possible to get a false positive with filters like ignore_labels.

Workload Types

Expeditor has different types of workloads, each representing an object from a different integrated system. The type of Workload dicates that construction of the event ID, as well as the metadata that is made available with that workload.

The following fields are available on every workload, and are used primarily for routing and other core functionality.

Field Description
id A unique identifier for the workload.
event The name of the event.
type The type of workload.
name A user-friendly name for the workload.
description A short description of the event.
html_url An external URL to view the “thing” that triggered the event.
date The iso8601 timestamp for when the workload was received.
agent_id The project agent assigned the workload.

agent

An action taken against an agent.

Event ID: <AGENT_ID>:<ACTION>:<DATE>

Field Description
action The action that was taken against the agent.
target_agent_id The name of the agent that was acted upon.
triggered_by The name of the user who triggered the action.

Supported Events

Event Description
agent_refreshed The agent was manually cycled by a person. Used common to re-apply configurations such as pipelines.

artifact

A compiled Omnibus artifact that typically uses a MAJOR.MINOR.BUILD/PATCH version scheme.

Event ID: <CHANNEL>:<PRODUCT_KEY>:<VERSION>

Field Description
channel The name of the release channel.
product_key The short-code name of the product.
product_name The full name of the product.
version The X.Y.Z version.

Supported Events

Event Description
artifact_published A chef.io package is published to a new channel.
Sample Subscription
subscriptions:
  - workload: artifact_published:stable:chef:*
    actions:
      - noop:sample_action

buildkite_build

A Buildkite build.

Event ID: <AGENT_ID>:<PIPELINE_NAME>:<BUILD_ID>

Field Description
pipeline_id The UUID of the pipeline.
pipeline_full_name The full name of the pipeline (e.g. [chef/chef:master] verify)
pipeline_name The name of the pipeline (e.g. verify)
pipeline_slug The slug of the pipeline (e.g. chef-slash-chef-master-verify)
build_id The UUID of the build.
build_number The build number.
build_message The build message.
build_commit The git SHA used for the build.
build_branch The git branch used for the build.
build_state The state of the build.

Supported Events

Event Description
buildkite_build_running The build is currently running jobs.
buildkite_build_scheduled The build has yet to start running jobs.
buildkite_build_passed The build passed.
buildkite_build_failed The build failed.
buildkite_build_blocked The build is blocked.
buildkite_build_canceled The build was canceled.
buildkite_build_canceling The build is currently being canceled.
buildkite_build_skipped The build was skipped.
buildkite_build_not_run The build wasn’t run.
Sample Subscription
subscriptions:
  - workload: buildkite_build_passed:{{agent_id}}:verify:*
    actions:
      - noop:sample_action

buildkite_hab_build_group

A collection of Habitat packages that were built in a Habitat Build pipeline.

Event ID: <AGENT_ID>:<GROUP_ID>:<DATE>

Field Description
group_id The unique identifier (channel name) for the build group.
pkg_idents A hash of of pkg_idents mapped by <PKG_NAME>-<BUILD_TARGET>.

Supported Events

Event Description
buildkite_hab_build_group_published Some number of Habitat packages were built and successfully uploaded to the Depot.
Sample Subscription
promote:
  channels:
    - dev
    - acceptance
    - current

subscriptions:
  # Promote the just built packages to the dev channel
  - workload: buildkite_hab_build_group_published:{{agent_id}}:*
    actions:
      - built_in:promote_hab_packages

docker_image

A Docker image.

Event ID: <NAMESPACE>/<IMAGE_NAME>:<TAG>:<DATE>

Field Description
namespace The tianon in tianon/true:latest.
image_name The true in tianon/true:latest.
tag The latest in tianon/true:latest.
sha256_digest The Content Digest for the published image.

Supported Events

Event Description
docker_image_published A Docker Image is published to the Docker Hub.
Sample Subscription
subscriptions:
  - workload: docker_image_published:chef/chef:*
    actions:
      - noop:sample_action

generic

A generic workload that contains no metadata beyond the defaults mentioned above. It is used to easily trigger certain action sets for testing purposes. You are free to use the generic workloads for other purposes, but keep in mind that generic workloads are global (so be careful).

Event ID: No structure - whatever you want.

Supported Events

Event Description
generic_workload_published This is an event used in testing to trigger specific actions.
Sample Subscription
subscriptions:
  - workload: generic_workload_published:*
    actions:
      - noop:sample_action

hab_package

A Habitat package.

Event ID: <CHANNEL>:<PKG_ORIGIN>/<PKG_NAME>/<PKG_VERSION>/<PKG_RELEASE>

Field Description
pkg_origin Denotes a particular upstream of a package.
pkg_name : The name of the package.
pkg_version The version of a package.
pkg_release The UTC datetime stamp when the package was built. This value is specified in YYYYMMDDhhmmss format.
pkg_ident The fully-qualified identifier of a package that consists of origin/name/version/release.
channel The channel to which the package was published.

Supported Events

Event Description
hab_package_published A Habitat Package is published to the Habitat Depot.
Sample Subscription
subscriptions:
  - workload: hab_package_published:stable:core/glibc/*
    actions:
      - noop:sample_action

incident_status

Status update for an ongoing incident.

Event ID: <SERVICE>:<STATUS>:<DATE>

Field Description
incident_impact The impact of the incident.
incident_name The name of the incident.
incident_status The current status of the incident. One of the following: identified, investigating, resolved, monitoring, postmortem, scheduled, inprogress, verifying, completed.
incident_timestamp A timestamp relevant to the incident.
service The name of the service.
update_body The message sent along with the status update.

The following services are supported:

Timestamps

incident_status Relevancy of incident_timestamp
monitoring When the incident started.
resolved When the incident was resolved.
scheduled When the maintenance is scheduled to start.
* When the incident was last updated.

Supported Events

Event Description
incident_status_updated The status of an incident has been updated.
Sample Subscription
subscriptions:
  - workload: incident_status_updated:habitat:*
    actions:
      - built_in:notify_chefio_slack_channels

promotion

A promotion of a project.

Event ID: <AGENT_ID>:<PROMOTABLE>:<DATE>

Field Description
notify_channels Additional Slack channels that should be notified when promotion is complete.
project The name of the project you are promoting. This is either the Agent ID or a project alias. Backwards compatible with thing.
promoter The Slack username of the person to trigger the promotion.
promotable The reference to what that you are promoting. Either a version (X.Y.Z) or a channel (e.g. stable).
source_channel The name of the channel in which promotable currently exists. May be the same as promotable.
target_channel The name of the channel to which the promotable of thing should be promoted.

Supported Events

Event Description
project_promoted An authorized user manually triggers a promotion for the artifacts associated with a specific project.
Sample Subscription
subscriptions
  - workload: project_promoted:{{agent_id}}:*
    actions:
      - noop:sample_action

pull_request

A GitHub pull request.

Event ID: pull_request_<ACTION>:<REPO>:<BRANCH>:<NUMBER>:<GITHUB_DELIVERY_UUID>

Field Description
repo The full name of the repository (e.g. chef/chef).
branch The target branch of the pull request.
number The pull request (also Issue) number.
action One of the following: assigned, unassigned, labeled, unlabeled, opened, edited, closed, merged, reopened, or synchronized.
title The title of the pull request
body The main description of the pull request.
author The GitHub user name of the person who opened the pull request.
head The name of the HEAD ref for the pull request (e.g. the branch name).
head_repo The name of the repostiory from which the pull request was opened.
previous_commit The SHA of the most recent commit on head before latest_commit.
latest_commit The SHA of the most recent commit on head.
merge_commit The SHA for the Merge Commit of the pull request.
event_sender The GitHub user name of the person who performed the action.
commits The number of commits included in the pull request.
changed_files The number of files change in the pull request.
additions The number of lines added in the pull request.
deletions The number of lines deleted in the pull request.
comments The number of comments associated with the pull request.
review_comments The number of review comments associated with the pull request.
modified_files Array containing the names of the files that were modified in the pull request.
issue_labels Array of GitHub labels applied to the pull request at the time of the Event.

Supported Events

Event Description
pull_request_closed A Github pull request is closed, but not merged.
pull_request_merged A Github pull request is merged.
pull_request_opened A Github pull request is first opened.
pull_request_synchronized New commits are pushed to an existing Github pull request.
Sample Subscription
subscriptions:
  - workload: pull_request_merged:{{github_repo}}:{{release_branch}}:*
    actions:
      - noop:sample_action

ruby_gem

A Ruby gem.

Event ID

Gem Platform Event ID Format
ruby <GEM_NAME>-<VERSION>
All Others <GEM_NAME>-<VERSION>-<PLATFORM>
Field Description
gem_name The name of the gem.
version The version of the gem.
platform The platform for the gem.
sha The Git SHA associated with this version of the gem.

Supported Events

Event Description
ruby_gem_published A Ruby gem is published to rubygems.org.
Sample Subscription
subscriptions:
  - workload: ruby_gem_published:chef-*
    actions:
      - noop:sample_action

schedule

A workload generated by a schedule defined in a project.

Event ID: schedule_triggered:<AGENT_ID>:<NAME>:<DATE>

Supported Events

Event Description
schedule_triggered The time specified in the cronline of the schedule has arrived, and the workload was generated.
Sample Subscription
---
schedules:
  - name: sample_schedule
    description: A sample schedule
    cronline: "0 0 * * *"

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

staged_workload

A workload that has been added to a staging area.

Event ID: staged_workload_released:<AGENT_ID>:<STAGING_AREA_NAME>:<DATE>

Supported Events

Event Description
staged_workload_released The workload has been released from a staging area.
Sample Subscription
staging_areas:
	- long_running_docker_build

pipelines:
  - build/docker

subscriptions:
  - workload: pull_request_merged:{{github_repo}}:{{release_branch}}:*
    actions:
      - add_to_staging_area:long_running_docker_build
  - workload: staged_workload_released:{{agent_id}}:omnibus_build:*
    actions:
      - trigger_pipeline:build/docker
	- workload: buildkite_build_passed:{{agent_id}}:build/docker:*
    actions:
      - unlock_staging_area:long_running_docker_build

Completed Workloads

Sometimes, when you are chaining action sets together, you want to trigger actions not on the Event itself, but on the successfull processing of an event by a specific project.

Sample Subscription
# Execute an action set when the `chef/example:master` agent has successfully
# processed the `project_promoted:chef/example:master:dev` workload.
subscriptions:
  - workload: chef/example:master_completed:project_promoted:chef/example:master:dev
    actions:
      - noop:sample_action

Environment Variables

Expeditor makes available the fields of the workload to bash actions and Buildkite pipeline builds as environment variables. Because the workload can contain data structures that are not supported in bash, we flatten the fields in the workload down to strings. See below for an example of the various type translations.

Sample Workload Object
{
  "event": "pull_request_merged",
  "body": "",
  "previous_commit": null,
  "commits": 1,
  "modified_files": [
    ".expeditor/config.yml",
    "README.md"
  ],
  "scm_settings": {
    "github": {
      "repo": "chef/example",
      "branch": "master"
    }
  },
  "agent_config": {
    "habitat_packages": [
      {
        "demo": {
          "origin": "chef",
          "source": ".",
          "export": [],
          "bldr_paths": [
            "*"
          ]
        }
      }
    ],
    "changelog": {
      "categories": [
        {
          "Type: New Resource": "New Resources"
        }
    }
  }
}
Sample Environment Variables
EXPEDITOR_EVENT=pull_request_merged
EXPEDITOR_BODY=
EXPEDITOR_COMMITS=1
EXPEDITOR_MODIFIED_FILES_0=.expeditor/config.yml
EXPEDITOR_MODIFIED_FILES_1=README.md
EXPEDITOR_SCM_SETTINGS_REPO=chef/example
EXPEDITOR_SCM_SETTINGS_BRANCH=master
EXPEDITOR_AGENT_CONFIG_HABITAT_PACKAGES_0_DEMO_ORIGIN=chef
EXPEDITOR_AGENT_CONFIG_HABITAT_PACKAGES_0_DEMO_SOURCE=.
EXPEDITOR_AGENT_CONFIG_HABITAT_PACKAGES_0_DEMO_BLDR_PATHS_0=*
EXPEDITOR_CHANGELOG_CATEGORIES_0_TYPENEWRESOURCE=New Resources

Empty workload settings are ignored. Please note that EXPEDITOR_PREVIOUS_COMMIT and EXPEDITOR_AGENT_CONFIG_HABITAT_PACKAGES_0_DEMO_EXPORT are missing because they are “empty”.