Sleuth's Custom Automation Framework Deep-Dive: Triggers

Automating your daily tasks can be such a satisfying experience, especially when it lets you focus on what you actually want to do that day. Once you the actual task you want to automate in mind, you need to consider when this task should actually run.

In this vein, in this next part of our deep-dive into Sleuth’s Custom Automation Framework we will cover the part that is responsible for defining when an Automation should execute: triggers.

Triggers Overview

Within Sleuth’s Custom Automation Framework, triggers are the events that kick off the entire process and workflow that we are automating.

A Sleuth Automation can have any number of triggers, ensuring that the automation execute on any number of events. A full list of available triggers can be found in the Triggers section of Sleuth’s Custom Automation Framework documentation.

To make things a little bit easier, the available types of triggers can be grouped together under deploy, cron, PR, and WIP (Work in Progress) categories, and we will cover each type below.

Types of Triggers

Deploy Triggers

A deploy trigger, as the name gives away, occurs when Sleuth has registered a deploy.

If you’re not familiar with deploys in Sleuth here’s a quick tl;dr: Sleuth gives insight into a team’s DORA metrics by connecting to both a git repository and a CI/CD pipeline in charge of deploying the changes from said repository, and deploys are the collection of changes (commits, PRs, issues, etc.) that are pushed each time a deployment pipeline is run.

There are a few different types of deploy-related triggers, specifically:

• deployed - This even happens each time a deploy has been registered with Sleuth.
• deployed_duration - This event allows for an automation to kick off based on how long a deploy has been active in a particular environment. Common scenarios where this can be useful would include auto-promoting a deploy from staging to production after it has had a healthy soak period, or posting a message in a Slack channel after a certain duration to encourage a dev team to manually promote a deploy from staging to production.
• deploy_message_reaction - When a deploy happens, Sleuth can post a message to a channel in Slack. Whenever a user reacts to the deploy message with an emoji, this deploy event triggers. Useful for automations that want to do something based on Slack message interactions. A good example is automatically deploy from staging to production with enough reactions.
• deploy_health_received - After a deploy has landed in an environment Sleuth checks the sources used to define “Failure Rate” (one of the four DORA metrics), and once this information has been gathered the deploy event triggers. This event is useful if you want to automatically do something with a deploy when everything is healthy, or do something specific when there is an incident or something similar in the environment the deploy landed in. A good example is posting a message in a Slack channel if a deploy lands in an environment and there is an active incident.

The nice thing about this type of trigger is that once it has been installed it can easily be used for all repository and pipeline combinations added into Sleuth with minimal configuration.

Pull Request Triggers

Pull request triggers offer various events related to any given pull request available in a repository connected into Sleuth.

• pr_opened - This event occurs whenever a connected git repository opens a new pull request
• pr_open_duration - This pull request trigger is used to focus on a time duration that a pull request has been opened for. A great example of using this trigger is to notify a Slack channel after a pull request has been opened for a certain number of hours or days, reminding teams to take action on the pull request.
• pr_edited - This will cause an automation to run whenever a particular pull request has been edited. This can include running an automation whenever a pull request title gets updated to ensure it fits a particular description.
• pr_others_edited - This will run an automation for all other pull requests than the current one. Useful in a scenarios where we need to check what is going on in other pull requests. An example would be checking if another pull request has a blocker label and therefore prevent the current pull request from being merged
• pr_merged - Occurs whenever a pull request in a connected repository is merged. Can be used to add a comment to a related issue whenever a pull request is merged to help keep everyone in-sync with changes rolling out
• pr_reviewed - This event happens whenever someone reviews a pull request, including adding comments to the pull request. A great use-case for this for teams where their git repositories are very noisy and have tons of notifications. Automatically sending a DM the author of a pull request whenever somebody reviews their pull request can help cut through the noise.

CRON Triggers

A CRON trigger will fire at any given time interval, allowing developers to run Sleuth Automations on a regular basis. There are a few different types of CRON triggers to help narrow down if a Sleuth Automation should be run for a specific team, project, or on a list of currently open pull requests

• cron_team - This will trigger a Sleuth Automation focused on a particular team, or set of teams at a regular time interval. Can be used to update a Slack channel with team-specific metrics on a daily basis.
• cron_project - This will trigger a Sleuth Automation focused on a particular project (a collection of repositories and sources of failure rate in Sleuth) at a regular time interval. A good use-case would be to post the health status of a project on a daily basis.
• cron - This will kick off an automation on a regular interval for open Pull Requests of any linked repositories, also known as Work in Progress items within Sleuth. Can be used to regularly check in on the number of open Pull Requests for linked repositories on a daily basis.

Work in Progress Triggers

Work in Progress (WIP) is a Sleuth-specific terminology that treats open pull requests for any repository linked to Sleuth as an item that is currently being worked on. WIP is mainly used to gain insight into how tasks developers are actively working on will influence any DORA metric. This is super useful when building automations related to any in-flight work.

• wip_set_duration - This event will kick off after a PR has been open for a certain amount of time. Often used when teams want to focus on improving how they work with PRs and examples include trying to reduce time to review, or reduce how long it takes to deploy a PR. An automation can kick off to notify a Slack channel and help prioritize any open PR at risk of missing internal goals.

Next Up: Conditions

Triggers are just one part of Sleuth’s Custom Automation Framework and they specify when the Automation should run. As seen above, there are plenty of opportunities in any existing workflow for delivering software where a trigger can be used to start any Sleuth Automation.

Next up in this series is Sleuth’s Custom Automation Framework Deep-Dive: Conditions. In this article we will cover the building block which defines the checks that need to happen to ensure the Sleuth Automation is triggered under the right circumstances.