Delete Sync Meetings from Your Calendar with Sleuth Automations

Sleuth Automations are fantastic tools to help engineering teams automate repetitive or manual tasks, reduce toil, and enforce best practices across any team or project. These Automations are one-click install, one-click uninstall, which make them super convenient to experiment with and create the perfect mix for your project or team.

There’s a large number of Automations listed in the Sleuth Automations marketplace, including notifications like previously discussed in “Notifications: don’t let silent disasters crush your dev team“ and best practice guardrails, as covered in “Guardrails: Engineering teams head for a deadly crash without them”. The list is already pretty long, and the Sleuth team keeps on adding more and more! Under the hood of each of these Automations is a descriptive YAML language which the Sleuth team has used to create each and every one of these powerful tools.

While most Sleuth users will use the existing Sleuth Automations as they come out-of-the-box, in some cases we may want to tailor an Automation to fit our organization, or create something completely new from the ground-up, and this is where Sleuth’s Custom Automation framework come into play.

Today I’m going to walk through how you can take any existing Sleuth Automation and make it your own, so join me in the journey of creating our first custom Sleuth Automation!

Scenario: FooCorp and Important Features

In the scenario we are working with today we are an engineer working for FooCorp. Within FooCorp their issue tracker, Jira, is the source of truth. Leadership, product management, and developers alike all refer to things that are being worked on through Jira issues. However, people aren’t always diligent about updating Jira issues for various reasons. This results in people chasing team members to figure the status of any given issue and figure out if changes have been pushed to production or not.

To address the above the team has decided to focus on just the most important issues for now, only requiring team members to add a comment whenever a critical feature has been addressed. To organize things on the GitHub side, the superimportant label should be added to every pull request that tackles one of these features. Any time changes in a superimportant pull request are pushed to staging or production the related Jira issue should be updated.

Even with these updates to the workflow, there is a lot of time spent on discussing just the superimportant issues in daily stand-ups and there is now discussion of adding an additional daily meeting just to discuss the status of these important features. Rather than add another meeting to our calendar, what if we could automate this entire process?

This is exactly why Sleuth released Sleuth Automations.

Finding a Similar Sleuth Automation

Chances are that there will already be a Sleuth Automation that does exactly what we are looking to do, but if we can’t find exactly what we need then we need to create our own custom Sleuth Automation. Rather than start completely from scratch each time we need to customize something, it’s always easier to find something that is close enough that we can build on top of, so let’s start looking around the Sleuth Automation Marketplace and see what we can discover.

The core functionality of our Automation is to comment on a Jira issue. So, let’s search for “comment” in the marketplace and see what we discover.

That first Sleuth Automation, Action: AT-101 seems pretty promising since it adds a comment on an issue when a PR deploys to production.

When we click on AT-101 we get to see a description of what this Sleuth Automation does, a button that let’s us install this Sleuth Automation, and we also have a tab called “YAML” which lets us see the underlying YAML for this Automation.

Let’s put a pin in the YAML tab for now, but based on the description this is very close to what we want to do. However, this Automation is not quite what we need because it only focuses on the production environment, and it will comment on our Jira issue for all related pull requests, not just the superimportant ones.

While not 100% what we need, let’s keep this Automation open in a separate tab since this seems like a good place to start and might be the first part of the equation.

Clicking around a bit more, or searching for “PR”, we can find Notification: NT-112, which is a Sleuth Automation that will notify the list of reviewers on a pull request when a particular label is added. What if we take the part of NT-112 that pays attention to labels on pull requests and combine it with AT-101? Seems like we have the second half on our equation!

With the two halves of our equation ready to go, let’s create a new custom Automation and combine the two existing Sleuth Automations!

Using Sleuth’s Custom Automation Framework

In the same Sleuth Automations Marketplace we’ve been navigating through so far we can find the “Custom” type, which will let us install a fresh custom Sleuth Automation.

Clicking on the install button after navigating to the Custom YAML Automation page, we’re greeted with a page that let’s us select where to install this custom Automation, the name of the Automation, as well as a quick description. We also have a field that is ready to accept some YAML!

Focusing on the top half, we will install this custom Automation in a specific Sleuth project (Sleuth Automations can also be installed on a team-by-team basis), and we’ll give an appropriate name and description for what this Automation does.

Now for the YAML portion. First, we believe that AT-101 seems like a good foundation for this custom Automation since it mostly does what we need. So, let’s jump back to AT-101, click on the "YAML" tab, then copy and paste this YAML into our "Rules in YAML format" text area.

rules:
  - tool_add_comment_on_issue:
      actions:
        - notify_mentioned_issues
      conditions:
        - environment='[[ Environment ]]'
      triggers:
        - deployed

Going from top to bottom of this YAML, what we are doing here is:

• We give a unique ID for our Automation tool_add_comment_on_issue
• We define a list of actions. Actions within Sleuth Automations are things we want to do within this Automation (e.g. send a message to a Slack or MS Teams channel, or comment on an issue) and can be chained together. Actions are built-in to the Sleuth Automations language and there’s a large list of available actions that we can take advantage of. We can find a full list of these by following any of the “actions documentation” links in the installation screen we currently are viewing. In this case notify_mentioned_issues is all we need to add a comment to a related issue, which link directly to the related code deployment by creating a clickable link within a comment following this format: “Referenced in a {name of code deployment} to {environment}”
• We define the the conditions for when this Sleuth Automation should run, which in the current case is whenever a change is pushed to a particular environment (which, if we installed AT-101 is defined in a dropdown of available environments for our project)
• We decide what should trigger this Sleuth Automation, which in this case is whenever changes are deployed

For a more in-depth look at what this YAML means, as a cookbook that contains tons of examples of how to write your own Sleuth Automations, you can refer to the Sleuth Automations documentation.

Now, for the next part we can look at the YAML for NT-112 and try to uncover how we can look out for pull requests that are using a particular label. We see that in the conditions section we have the pr_labels variable, which in the current YAML points to [[ PR label ]] which is actually pulled from the form that we fill out when installing NT-112. This variable can also accept a hard-coded string, which means we can add in our superimportant label.

So, let’s take this one variable in NT-112 and add it to the YAML of our custom Automation, and say that we are looking for the superimportant label.

rules:
  - tool_add_comment_on_issue:
      actions:
        - notify_mentioned_issues
      conditions:
        - environment='[[ Environment ]]'
        - pr_labels='superimportant'
      triggers:
        - deployed

In its current state, our Automation also has an environment label in our conditions area, which means we can limit when this Automation runs based on a particular environment. However, in our case we want the full history of the changes being pushed through our environments since it is superimportant so let’s remove that variable.

rules:
  - tool_add_comment_on_issue:
      actions:
        - notify_mentioned_issues
      conditions:
        - pr_labels='superimportant'
      triggers:
        - deployed

The last thing we need to do is give this rule a new name. While not necessary when this is our one and only Sleuth Automation, we can quickly run into issues when we install a few Sleuth Automations and then create our own custom ones by copying and pasting YAML.

Quick note here, whenever we later view our custom Automations Sleuth will remind us to make sure that the rule name is unique with this handy warning:

So, let’s rename this rule to comment_on_issue_important_prs.

rules:
  - comment_on_issue_important_prs:
      actions:
        - notify_mentioned_issues
      conditions:
        - pr_labels='superimportant'
      triggers:
        - deployed

Just to make sure we don’t write poorly formatted YAML, or run into issues down the line, Sleuth provides a quick YAML validation check and display any potential issues underneath.

In our case our YAML is good to go - thanks for checking Sleuth!

Trying our New Custom Sleuth Automation

Let’s take our new Sleuth Automation for a spin.

First, we’ll create a Jira issue that we want to automatically update as we deploy our changes.

For this particular example, the most important thing for us to keep in mind is the issue key associated with this issue. In our case this is SJ-9.

The reason this issue key is important is because Sleuth will use this issue key to connect any work that is being done in our git repository to our issue tracker. This includes any pull requests, commits, and even branch names that our engineering team is working on. With some quick integration with both GitHub and Jira in Sleuth (which FooCorp already did during the initial setup of Sleuth) all that we need to do from now on is make sure we include the issue key is mentioned somewhere in the changes we are pushing out.

Side-note: if including issue keys in your pull requests or commit messages is something your team is struggling with today there are handy Sleuth Automations that can be used out-of-the-box to prevent pull requests from being merged if a issue key is missing from the pull request title, or from the pull request description!

So, let’s open up a pull request with some changes, add in #SJ-9 in the title, add the superimportant label, and them merge the PR and push the changes through our various pipelines to send out these changes to staging and production.

If we have integrated Sleuth with Slack or MS Teams we can get handy notifications along the way letting us know that changes have been deployed. This can be configured to display a notification for each environment in unique channels. In this case we have another Automation that lets us know when a deploy has soaked for a certain amount of time (3 minutes in this case) in the staging environment, which could be useful in letting us know if changes are ready to be promoted to production:

We can also look at the details of the deploy to see the overall Change Lead Time (CLT) for these changes, including how long it took to deploy after our pull request was merged:

This confirms that our changes have landed in each of our environments (notice the checkmark next to Production and Staging). Now, let’s check what this looks like on our Jira issue:

The links in the comments above will navigate users to the deploy detail screen in Sleuth to give anyone within FooCorp the ability to review the various commits and pull request that represent these changes.

We have just saved FooCorp countless of hours of meeting time that can now be spent on working on more features, no matter if they are superimportant or just lower priority. We also can’t forget about the human side of this as we no longer need to constantly remind our teams to update these important Jira issues, which leads to less friction between team members as well.

I’ll call this a great success!

Taking Your Sleuth Automations to the Next Level

What we covered today was a simpler example of how to use existing Sleuth Automations to create a new custom Automation. If you would like to learn more and see what else custom Sleuth Automations are capable of, here are some great links to our documentation and Cookbook that is full of great Automation ideas and recipes:

• Sleuth Automations Documentation
• Sleuth Custom Automations Cookbook

Go Out and Automate

Throughout this post we managed to completely automate the process of commenting on a Jira issue whenever important changes were being deployed throughout our various environments - all done with just a little copy and pasting of some YAML.

While the scenario was hypothetical in the case of FooCorp, it’s not that farfetched to imagine yourself on a team that is actually facing that exact same problem. I’ve personally lived through many hours of sitting in meetings that could have been completely replaced by this exact Automation. Imagine all the saved time of not just sitting in said meeting, but also the time that would be spent preparing for said meeting (and any action items afterwards).

This is just a small example of the power of Sleuth Automations and creating custom Automations, and whether your team uses something out-of-the-box or creates something unique to your own team, I encourage you to go out and automate!