Article summary
GitHub Actions are a great way to implement CI/CD into your projects, whether personal or professional. GitHub has a lot of great tools to help with CI/CD, but GitHub Actions in particular is very helpful. However, writing actions can be tedious and a little annoying, especially if you don’t know what you’re doing. On top of being difficult to write, they’re extremely hard to test. This is because, to ensure that a workflow is working properly, you have to use certain triggers, or the workflow has to already exist on main to access it.
The Problem
There are a few different ways around this. You can change the workflow to run on demand. Or, you can modify the workflow in certain ways so you can test it in GitHub without merging your pull request. However, more often than not, you need to merge your PR that contains the GitHub Actions workflow to test the workflow in the Actions suite.
This was something that, when I was just starting out, frustrated me a lot, so I started looking into alternatives. I wanted to be able to push up a workflow, open a pull request, and provide testing instructions to test it locally. I wanted to feel confident that when the PR gets approved, it’s not just a “looks good to me.” The workflow is going to do exactly what I told you it was going to do and not result in an immediate failure because the workflow can’t build its Ubuntu version in GitHub. This then results in another small commit and a PR where we rinse and repeat.
The Solution
Luckily, I was able to find a solution to this pain point. A resource and tool I found incredibly helpful with this was Nektos repo for act. Essentially, act is a way to run your GitHub Actions locally using Docker. When you install act and use it inside your repo to run your workflow, act then uses the Docker API to pull images that take in the environment variables and have the file system set up the same way GitHub will when it runs the GitHub Actions.
This project is really, really cool because it allows you to create really complicated workflows and test them fully. You can test making a fake PR and having it trigger the linter, or test all those tricky workflows and be able to know with full confidence that it will, in fact, run when that occurs.
For example, on a recent project where we leverage GitHub Actions, we used act for something simple like running the unit test suite when someone creates a PR. This workflow couldn’t be tested in GitHub as just a PR because the GitHub Actions suite only grabs workflows from the main branch. That made it difficult to test whether we had selected the correct versions of node, Linux containers, or build at all. However, by using act, we were able to ensure that if it received a pull_request trigger, the workflow would run, and the dependencies were correct and built. However, it wouldn’t happen if we pushed code or made an issue. This allows me to have the confidence that when that PR gets merged in, it will build and do exactly what I wanted, when I wanted it.
Getting Started with act
To get started with act, ensure you’ve installed Docker, and install act using their installation guide for your machine. Then, once it’s installed, open a repo that has a .github/workflows folder (that ideally has workflows in it) and run act -l to get a list of all the workflows in your repo and what triggers them. Then you can just run act [event trigger] (so in my case it was act pull-request) and watch your workflow run.
All this is to say, act is an extremely versatile tool. It was extremely helpful for testing my GitHub Actions locally. It’s a great way to learn more about Github Actions, and I highly recommend you check it out.