GitHub Actions 101

What are Workflows?

We'll start with workflows. Workflows are your pipeline as code, and can be equated to Jenkinsfiles, Travis.yml's, etc. They live within the repository they will interact with, and respond to Events (discussed more below) to take action on your code. They're written in YAML syntax.

These workflows are often used for CI/CD, however you could also do something like auto-respond to new issues from first time contributors, welcoming them to your project and thanking them for opening an issue. Other examples could include compliance and legal concerns, such as enforcing branch protections, licensing, and more.

One thing to note is that as of the writing of this article (June 2020), GitHub Actions workflows need to live in the repository themselves. There is a common ask to have organization-level workflows as well, so hopefully we will see this in the future.

What are Events?

Events trigger the workflows we just discussed. GitHub Actions supports almost every Webhook event on GitHub, so things like issues opening/closing, pull requests being merged, deployments, etc. You can also use cron triggers to execute workflows on a set schedule.

What are Actions?

Actions are used by workflows to take specific action. These are written in JavaScript (Node or Typescript), typically, but can also be containers that spin up and perform some tasks.

Actions are reusable units of code, and perform specific tasks based on inputs your workflow provides and the event payload contains.

What are Self-Hosted Runners?

The Actions runner source code is open source, and allow you to create your own custom runners with whatever customizations you need (more hardware, a different operation system, on premises, in the cloud, etc).

Self-hosted runners are free to use with GitHub Actions, because you are responsible for the cost of maintaining your runner machine(s).

GitHub Actions API

GitHub's API is really robust, and allows you to do just about anything via code that you could do on the UI. GitHub Actions continues this trend by providing a variety of REST API endpoints.

These endpoints allow you to interact with build artifacts, get information about the workflows being ran, specific build job details, and a way to manage Secrets.

JavaScript versus Container Actions

As mentioned previously, when you create a GitHub Action, you can choose to build a JavaScript action or Container action.

For JavaScript Actions, we find they execute faster and provide a better user experience, and also support Linux, MacOS, and Windows environments. Anything that compiles to JavaScript will work, so you can code in Node, TypeScript, etc.

Container actions can be written in any language you like, but only run on the Linux runners currently. They are a little slower, and provide a little less of a user experience, but are still very versatile.

Basically, choose whichever language and environment makes sense for you and your project.

Best Practices for GitHub Actions

When creating GitHub Actions, there are a few best practices to keep in mind.

First, always version your action releases with the releases and tags feature of GitHub. This allows your users to target a specific release, and not always pull the latest which could result in unexpected behavior.

Next, ensure you have proper documentation. You'll want to have a README with a sample workflow to execute your action, and this README is rendered on the GitHub Marketplace listing for your GitHub Action. You should also consider adding CONTRIBUTING docs, and other open source documentation.

Ensure you create an action.yml file, which provides the metadata around your action.

Finally, make sure you post your GitHub Action on the GitHub Marketplace.

When writing an action, there are two approaches that can be taken and should be discussed. These are chainable versus monolithic and are broken out below.

Monolithic Action Example

A monolithic action would mean your action is doing all the things in one "step" of a workflow file. For example, you could have an action that builds, tests, uploads build artifacts, creates a release, and sends a tweet about the release.

While this may sound appealing at first, one action to rule them all is very difficult to maintain and make modular. GitHub Actions shine when they are chainable, as discussed next.

Chainable Action Example

In contrast to a monolithic action, chainable actions are my preference. Consider this workflow as an example. Each bullet could be a seperate step, which means when debugging errors I know exactly what part of my pipeline is failing versus it being abstracted into a single step.

• Checkout code
• Lint code
• Build project
• Run Unit
• Run Integration Tests
• Run UI Tests
• Create a Draft Release
• Generate release notes
• Publish release
• Send tweet about release

As you can see, while there are many more steps to this workflow, they are very clear in what each step does. You can plug and play modular actions into each of these steps, which provides a better user experience.

Summary

In conclusion, GitHub Actions are very versatile, powerful, and allow you to automate all sorts of things. Look for future articles on GitHub Actions, and leave a comment about any actions you have built or plan to.

Further reading...

• Events that trigger workflows
• Hello, GitHub Actions!
• GitHub Actions: Continuous Integration
• GitHub Actions: Publish to GitHub Packages
• GitHub Actions: Continuous Delivery