Running a GitHub Action

Part of providing a first-class experience for GitHub users is to not have to learn a whole set of new concepts in order to use Terrateam. We want to fit into our user’s existing workflow and just add value. There are a few ways we accomplish this, the most obvious is rather than recreating a review system, our users just create pull requests and interact with Terrateam through the pull request. Additionally, rather than implementing a new CI/CD system, we leverage GitHub Actions. GitHub Actions are very powerful, allowing users to implement complex workflows. A GitHub Action responds to an event, for example updating a pull request or commenting on an issue. So, how does Terrateam run its GitHub Action?

While a GitHub Action can have a complex workflow, we chose to have a simple one which only responds to the workflow_dispatch event. A workflow_dispatch event is roughly equivalent to manually starting an action.

One of our goals is to only execute a GitHub Action when there is work for it to do. Not all pull requests require a GitHub Action to run, nor do all comments on a pull request. For example, we only want to run a GitHub Action if a user opens a pull request that modifies Terraform files. The primary reason we want to be frugal with actions is for our customers: running a GitHub Action is not free. It’s likely that they are using GitHub Actions for other parts of their workflow and we do not want to be hogging all the minutes.

To execute an action:

1. A user performs an operation, such as opening a pull request, closing one, or commenting on one. This results in an event being sent to the Terrateam server.
2. Terrateam evaluates the event to determine if the GitHub Action should be run. This requires fetching the Terrateam configuration in the branch and comparing it to the changes in the pull request. If there are no changes that require a Terraform run, the event is discarded, otherwise a workflow_dispatch event is published.
3. The GitHub Action executes the required work, generally running a Terraform operation in each directory that has changed. Once complete, it publishes the results back to the Terrateam server.
4. Finally, the Terrateam server publishes any results back to the pull request, in the form of a comment as well as updating any status checks.

                ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
                ┃          GitHub Pull Request           ┃ ◀┐
                ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛  │
                  │                                         │
                  │ (1) Event (Open, Close, Comment, etc)   │ (4) Post Results
                  ▼                                         │
                ┌────────────────────────────────────────┐  │
  ┌───────────▶ │               Terrateam                │ ─┘
  │             └────────────────────────────────────────┘
  │               │
  │ (3) Results   │ (2) workflow_dispatch
  │               ▼
  │             ┌────────────────────────────────────────┐
  └──────────── │             GitHub Action              │
                └────────────────────────────────────────┘

And that’s about it. Terrateam is consuming events and deciding if our GitHub Action should be run. There are some specific details that one needs to be careful about but we can cover that in another blog post.