GitHub Actions is a tool that allows developers to automate workflows related to their GitHub repositories. With GitHub Actions, developers can build, test, and deploy their code directly from GitHub. While GitHub Actions can be very useful, they can also be difficult to debug when things go wrong. When an action fails, it can be challenging to figure out what went wrong and how to fix it, since they can only run on Github, and you end up sending mock commits one after another to iterate through bugfixes. Moreover, it can be costly, as Github Actions are billed per minute. In this post, I will talk about a tool called Act, which allows developers to run Github Actions locally on your machine.
What are Github Actions?
Github Actions is a tool (system) developed by Microsoft to make day-to-day development tasks easier. It allows CI/CD (Continuous Integration/Continuous Deployment) integration with existing Github workflows. One of the main benefits of GitHub Actions is that it is very easy to set up and get started with, even for developers who are new to CI/CD systems. In addition to its simplicity, GitHub Actions is also relatively inexpensive compared to other CI/CD tools, making it a good choice for developers who are working on a budget. Another advantage of GitHub Actions is its strong community of users and developers, who can provide support and guidance when working with the tool. Overall, GitHub Actions is a powerful and user-friendly CI/CD system that is well-suited to developers of all skill levels. On the image above you can see the typical steps in a CI/CD system.
Why are they hard to debug?
Debugging and developing GitHub Actions can be challenging, especially for developers who are new to the tool. One of the main difficulties of working with GitHub Actions is that it can be difficult to run and debug actions locally, as they are executed on cloud servers. This can make it hard to test and troubleshoot actions before they are deployed, as developers must rely on logs and other remote debugging techniques. This can be especially frustrating for developers who are used to being able to run and test their code locally. They may find themselves pushing empty commits to trigger pipelines to run and fail again, thus wasting valuable time and resources.
If only we could run these actions locally! This would make them so much easier to develop and debug, while making it cheaper at the same time. Luckily for us, there exists just the tool to do this: act.
How does Act work?
Act is a CLI tool, written in Go, which closely mimics Github Actions’ own behavior Act reads in the GitHub Actions defined in the .github/workflows/ directory and determines which actions need to be run based on the dependencies defined in the workflow files. To execute these actions, act uses the Docker API to pull or build the necessary images, as specified in the workflow files. Once the images are prepared, act determines the execution path based on the dependencies and then uses the Docker API to run containers for each action based on the prepared images. This process closely mirrors the way that GitHub Actions are executed, with the environment variables and filesystem configured to match the GitHub environment. Overall, act provides a convenient way for developers to test and debug their GitHub Actions locally before deploying them.
How to install Act
Before installing Act, you need to make sure your system meets the prerequisites. Act relies on Docker, so you need to make sure you have it installed and have
docker command available in your terminal. You can follow these instructions on how to install Docker on your system: Windows, Linux, macOS.
After installing Docker, you can proceed to install act. Here are the instructions based on the platform of your choice:
yay -Syu act
dnf copr enable rubemlrm/act-cli dnf install act-cli
nix-env -iA nixpkgs.act
Linux/macOS (Bash script):
curl <https://raw.githubusercontent.com/nektos/act/master/install.sh> | sudo bash
brew install act
port install act
choco install act-cli
scoop install act
If none of these work for you, you can always download a binary and put in your PATH.
These instructions are retrieved in early 2023, and may become outdated. Refer to the project repo for updates.
How to use Act
To run your Github Action locally, navigate into your project folder (where
.github/workflows is located and run:
That is it! By default, it will run your
push action. To view all available actions, you can run:
$ act -l
To run a specific action, run:
$ act <ACTION NAME>
When you run Act for the first time, you will be prompted to choose a Docker image for your runner. Read their descriptions and choose one depending on how complex your workflows are. I chose “micro” for my basic JS testing workflow. This is the output I got when running
act on my React project:
You can see that Act successfully read my YAML file and ran basic JS tests in a docker container.
You can also add your Github Actions variables and secrets to Act to complete your testing. Just put them in
.env file (for variables) and
.secrets file (for secrets) like this:
Pros & Cons
Act is a wonderful tool for many reasons:
- It is much easier, faster, and cheaper to debug Github Actions locally before pushing them to the server
- Act works out-of-the-box with no additional configuration
- Mimics Github Actions behavior precisely
However, Act has a few shortcomings that may prevent some developers from using its full potential:
- Very large Docker image sizes; the full image that aims to provide all Github Actions features weighs 20+GB
- Cannot use custom containers feature; Github allows you to use custom Docker containers for yous jobs; you cannot do this with Act
- Cannot use non-linux containers; Github allows you to use Windows containers for your jobs, and Act cannot do that
- Act does not support Docker Context, so any jobs that rely on that will not work
- Github Actions Services are not supported; any job that uses those will fail
Act shows much promise, but it is still in early stages of development and it is hard to see how it can be used beyond the most basic Github Actions in hobby projects. I will follow closely the development of Act for more exiting features and parity with the mainstream Actions. I hope you enjoyed the read, and please let me know in the comment what do you think about Act!