Sleuth's Custom Automation Framework Deep-Dive: Conditions

Automating a task may seem as simple as defining a “just do the thing” function, but if we only focus on “the thing” to be done we miss out on understanding under what circumstances the function should execute. While we know when things should run based on triggers, but we also want to narrow down what we are automating to a specific situation (e.g. a deployment landing in our production environment) so that we only run the automation during the right circumstances.

This is where conditions come into play.

What Are Conditions?

Conditions are the part of Sleuth Automations that says “if this is true, run the Automation”.

Any Sleuth Automation can have [zero - N] conditions giving developers a wide range of possibilities to run automations every time a trigger event happens, or narrow things down and be extremely specific. You can even join together conditions by using and or or giving even more control over when and how Automations should run.

A condition is defined using the following pattern:

variable -> operator -> value

To put that into context, here are a few examples of conditions:

• environment='Staging' - In this case we are looking at the environment (variable) and ensuring it is equal (operator) to Staging (value).
• deployed_for>='5m' - We use the deployed_for (variable) and check that a deploy has been deployed for >= (operator) at least five minutes (value).

Variables and Operators

Condition Variables

To avoid making this post too long I won’t post all variables, instead you can refer to the Sleuth Custom Automations docs right here [hope we can open up the Custom Automations docs.

Note: the list below for each type may not be exclusive for just that type. For example, when we think about Change Lead Time in Sleuth we can look at average time to review pull requests on a deploy level, the individual pull requests of that deploy, and open pull requests the team is currently working on (Work in Progress in Sleuth). The list below is just a subset and intended to be examples to give you some insight into what is possible with conditions.

Types of Condition Variables

Deploy-Based Variables

A deploy in Sleuth represents a group of changes being pushed to an environment

• deployed_for - Checks how long a particular deployed has been on a particular environment. Can be used to check if a deploy has had a healthy soak time in staging and post a message to a channel letting the team know it is safe to push to production.
• environment - Check the particular deploy and which environment it is targeting
• num_pull_requests - Get a total number of pull requests that make up this particular deploy
• health - If we have sources for failure, check what the health of the deploy is. Useful in scenarios where we want to do something if a deploy is healthy, or if there is an incident then we may need to trigger some other automation a workflow

Pull Request-Based Variables

• pr_labels - Check which labels are applied to the pull request in question
• pr_title - Check the pull request title. Can be used to ensure we follow a particular pattern
• pr_open_duration_days - Check how long a pull request has been open for. If we want to minimize stale pull requests we may want to post a message in a Slack channel to ensure someone updates the pull request

Time-Based Variables

• month - Month of the year that you want to take this action in (values can range from 1-12)
• day_of_month - Day of the particular month you want to run this Sleuth Automation (values can range from 1-31)
• day_of_week - Day of the week you want to run a Sleuth Automation (values range from 0 - 6 and represents Mon - Sun)
• utc_hour - The UTC-based hour that you want the Sleuth Automation to run on (values range from 0 to 23)

Work in Progress-Based Variables

Work in Progress is a Sleuth-specific terminology where open pull requests are compared to the DORA metrics of any particular team or project, so many existing condition variables relate to DORA metric insights.

• coding_time - How long the deploy, pull request, or Work in Progress item has spent in Coding Time (from first commit until pull request is opened)
• review_lag_time - How long the deploy, pull request, or Work in Progress has spent waiting for a developer to review work done
• review_time - How long the deploy, pull request, or Work in Progress item has spent after the initial review (e.g. how much back-and-forth is happening before a pull request has been merged)

Condition Operators

After we have identified the variable(s) that we want to use we need to define what to look out for with that variable. Should we only kick off the automation of a pull request has waited for review for over a certain amount of time? Maybe we want to encourage users to ship smaller deploys by counting the number of pull requests so we want to keep them under a certain number.

With this in mind, Sleuth Automations offers a standard set of operators that we can use when evaluating the variables:

• > - Greater than
• >= - Greater than or equal to
• < - Less than
• <= - Less than or equal to
• = - Equal to. If either side is a list, it matches if those intersect.
• != - Not equal to. If either side is a list, it matches if those do not intersect.
• <> - Not equal to. If either side is a list, it matches if those do not intersect.
• ~= - Matches the value. If the value is a string, the 'regex' matcher is assumed. If either side is a list, it matches if those intersect.
• !~= - Doesn't match the value. If the value is a string, the 'regex' matcher is assumed. If either side is a list, it matches if those do not intersect.

What is Possible With Conditions

As a quick example of using Conditions we can look at the following Sleuth Automation that will automatically execute a deployment pipeline to deploy from staging to production if a merged pull request has the quickfix label:

rules:
  - quick-fixes:
      conditions:
        - environment='Staging'
        - pr_labels='quickfix'
      actions:
        - auto_approve_build: 'test-and-deploy'

The Right Circumstances

As seen through the small subset of available Conditions, there is rich foundation for defining the exact circumstances for when we want to execute any type of automation. Between the available variables and operators that can be used with them, and the fact that multiple conditions can be used in a single Automation, the possibilities are endless.

For a deeper look into the full list of available Conditions we recommend reviewing the condition section of Sleuth’s Custom Automation Framework documentation.

Next up in the series is Sleuth's Custom Automation Framework Deep-Dive: Filters, which covers how we can work with lists of items and filter down to a specific subset and trigger an automation on this subset.