Sleuth's Custom Automation Framework Deep-Dive: Filters

There may be scenarios where a Sleuth Automation takes an input that is a list of items, as opposed to just a single item. In these cases, should the Automation take all items into account or are we more interested in a subset? Maybe even just a single item?

Luckily we have a way to help us narrow things down and take out any items that we are uninterested in from a larger list thanks to Sleuth Automation filters.

What are Filters?

Filters in the Sleuth Automation framework are used with sets of Work in Progress Items, or sets of pull requests. These are not usable with the single, individual, instances of a work in progress item, pull request, or a deploy.

Filters in Sleuth Automations are defined using the following pattern:

variable -> operator -> value

In other words, using real examples:

• state='merged' to filter a list of pull requests to just those that have been merged
• environment='Production' to filter a list of pull requests to just those that are targeting our production environment

Filter vs. Condition

If you noticed a similar pattern between filters and conditions you’re not alone. The main difference is that conditions are applied to either an individual deploy/pull request/WIP item or the whole set of WIP items/pull requests. filters, on the other hand, are applied to each item in a set (a list of WIP items or pull requests).

In other words, if you have a collection of items and you want to grab a subset of items from that collection then filters are the way to go.

It should be noted that conditions and filters can be used together in the same Sleuth Automation.

Filter Variables and Operators

The similarity between filters and conditions do not end with their makeup. They actually share variables and operators as well.

As mentioned above filters will only work on lists of Work In Progress items or a list of pull requests, so one will have to pay attention to the variable in question by finding [Set of pull requests] or [Set of Work in Progress Items] next to the variable in the Sleuth Actions Documentation.

Examples include:

• coding_time - How much time has been spend coding (from first commit until a pull request has been opened)
• deploying_time - How much time the pull request has spent waiting to be deployed (has merged, but not yet deployed)
• pr_is_draft - Is the pull request a draft pull request?
• pr_is_ignored - Is the pull request of a type that we should ignore for our DORA metrics calculation?

Examples of Using Filters

As a quick example of how filters can be used we can look at a Custom Sleuth Automation that will post a message into a Slack channel when a pull request has been merged but is waiting to be deployed into production. This scenario can help encourage developers to publish smaller changes more often.

rules:
    - deploying-time-goal:
        description: Notify when deploying time exceeds a limit
        triggers:
          - wip_set_duration
        filters:
          - state='merged'
          - environment='Production'
        conditions:
          - deploying_time>'0d:0h:20m:0s'
        actions:
          - slack_channel_message:
              channel: '#dev-notifications'
              message: 'Oh-oh, {{ authors_slack }} the deploying time for this WIP item is too long!'

In the above example we can see that we are filtering WIP items (which are pull requests) to those that have been merged and are targeting the production environment.

More About Sleuth’s Custom Automations Framework

As a quick summary of what has been covered in this article, filters are meant to be used whenever a Sleuth Automation is dealing with a collection of items, which is usually a list of work in progress items or a list of pull requests. We now also have an idea of when a Sleuth Automation should fire, thanks to triggers, and what should be true in order for the Sleuth Automation to actually execute from the conditions that were configured.

As we wrap up the concept of a filter it is important to remember the other parts of Sleuth’s Custom Automations Framework which you can find links to over on the Sleuth's Custom Automation Framework Deep-Dive Series overview article.

With all of this knowledge it’s time to check out the last piece of this series, Sleuth's Custom Automation Framework Deep-Dive: Actions, in which we cover exactly the types of work that we can automate.