Integrating GitHub Actions into your Yetto workflow: Part One

The new GitHub Actions feature allows you to build automated workflows that observe and react to events that occur in your repository. Although still in beta, we've thoroughly enjoyed playing around with the feature, and have designed a few of our own actions that drive home our desire to bring more mature tooling systems to support teams. (Note that these actions are only available for Yetto beta users!)

The pieces of a GitHub Action

Before we share the automations we've built, let's quickly go over the components of a GitHub Action. GitHub Actions are composed of two parts:

  • The core of an action is the code that is executed on an event--in other words, what happens when a registered event is received. Just like third-party packages, they are shareable behaviors imported into repositories, and they define how your action behaves. This is what we've built and what we're open sourcing today.
  • A workflow file sets up the environment within which your action code executes. Workflow files can contain many different actions, and can perform different actions for different events. In other words, they define when your actions run. You create workflow files on your own.

As is true of the actions we're introducing, there's often a third component: a configuration file that lets you customize the content of the actions you've imported. (We'll be explaining this more in the sections below!) More information on the various concepts of GitHub Actions can be found on GitHub's help site.

Incorporating a GitHub Action into your repository

To start using a GitHub Action, you'll need to create a workflow file that refers to the external repository where the action code is kept. Yetto's actions are defined in the BottleCapTechnology/yetto-actions repository.

To add Yetto actions to your repository:

  1. If one doesn't already exist, create a directory in your repository called .github.

  2. Within that directory, create another directory called workflows.

  3. In the workflows directory, create a file called yetto.yml.

  4. Paste these lines into the yetto.yml file:

    on: [issues, issue_comment]
    name: Yetto Actions
    jobs:
      yetto_action:
        name: Perform Yetto Action
        runs-on: ubuntu-latest
        steps:
        - name: Yetto Action
          uses: BottleCapTechnology/yetto-actions@v0.0.1
          env:
            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    

This sets up your repository to make use of the Yetto actions we've defined in BottleCapTechnology/yetto-actions. We'll provide updates to this code as we create more actions and improvements in the future, which we'll announce here on the blog. To receive an update, you'll change the version suffix of the action from @v0.0.1 to the next release (@v0.0.2, @v0.1, @v0.2, @v1.0, etc.). For more information on the workflow syntax, check out the GitHub Help documentation.

Now that you've set up your repository to use Yetto actions, let's see what you get in our first release!

Automated replies

Support teams often receive an influx of tickets that have a common solution. In such cases, members of the support team may want to reply to everyone with consistent text that's agreed upon by the entire team.

While GitHub supports saved replies, these are kept on an individual's account, so sharing a common message amongst all members of a team can be difficult to synchronize. However, using GitHub Actions, we've made it so you can reply to an issue with a standard body of text when you apply a label to an issue.

To enable this workflow, you must first create that configuration file we talked about earlier. In your .github directory, create a file called yetto.config.yml, and paste the following lines:

auto_response:
  - on_label: not-this-product
    create_comment: |
      Hello there,

      Thanks for writing in, but unfortunately, we can't help you with your query.

      [/send]

auto_response is the top-level category for the action, and it contains the following options:

  • on_label specifies the label to react to.
  • create_comment defines the automatic text to post as a comment.

In this example, on any issue with the label not-this-product, GitHub Actions will create a new comment with the create_comment text that you've provided. You can customize the on_label and create_comment strings to be anything you wish. Best of all, because the comment ends with [/send], Yetto delivers this comment as an email directly to the user! Yetto also tags every incoming issue with its own Yetto label, so you can also set up the automation to immediately respond to users to let them know their message was received.

Parent issues

Catastrophes happen. When they do, users notice, and support is often inundated with tickets asking why a particular feature is broken and when it'll be repaired. In such situations, it can be helpful to have a single tracking issue that acts as a "parent" issue to other tickets.

With this action, you can close the parent issue and have it automatically reply to every issue deemed a "child" or "sub-issue". Just add these lines to your yetto.config.yml file:

close_child_issues:
  - on_label_parent: big-bad-boom
    for_label_child: child_of_big-bad-boom
    create_comment: |
      Hey there, just letting you know we fixed this problem.

      Thanks so much.

      [/send]

close_child_issues is the top-level category for the action, and it contains the following options:

  • on_label_parent specifies the label of the parent issue to watch for.
  • for_label_child specifies the label for all the child issues.
  • create_comment defines the automatic text to post as a comment.

To make use of this workflow, manually create a single issue and tag it with your predefined label; in this case, big-bad-boom. Then, label any incoming issue with the shared problem as child_of_big-bad-boom. When the issue is completely resolved, close the manual issue you created with the label big-bad-boom, and all the subsequent child issues will send the create_comment to users, then automatically close.

Custom commands

Many organizations have an on-call member outside of support, available to answer any questions or provide more context. On-call rotations change from week to week, but not everybody on the support team is able to keep up with those changes.

With this workflow, you can define a custom command to create an issue comment with some predefined text to call in a colleague:

custom_command:
  - on_phrase: "[/ping on-call]"
    create_comment: |
      @SkaLover95, this is your area of expertise, right? Can you help out?

custom_command is the top-level category for the action, and it contains the following options:

  • on_phrase is a string of text to listen to. Every issue comment that ends with this text is considered actionable.
  • create_comment defines the automatic text to post as a comment.

When you finish a comment with the text [/ping on-call], the create_comment string you wrote will be automatically pasted as a comment, allowing you to save time hunting for who to bring in. Be aware that your create_comment string must be the last line of text in a comment, so you can't provide more than one custom command per comment.

With this action, only the people who rotate in and out of on-call duties need to update this configuration file to better assist their support team.

What's next?

We've updated our help documentation to provide more information on configuring these actions.

We've also got a few more ideas for GitHub Actions we want to play around with, specifically around expanding the scope of actions to other organization members and repositories. Keep an eye on this blog and the yetto-actions repository for those actions in a future release, and happy supporting!