How to test Github Actions locally

One of the first things that I do in a project is to create a CD/CI process using Github Actions usually.
Why?
Because I would like to deploy as soon as possible with a process that launches tests for me automatically to understand if I can merge the feature and deploy it.
Nowadays Github Actions has a lot of integrations, tools, and containers to run your application.
But every time you create a Github Actions you need to test it and usually, you try to commit something to trigger it, you are testing manually your CD/CI.
For me it’s like testing my application manually, clicking buttons instead of automatic tests.

For this reason for me, it’s important to test my Github Actions without committing something because it’s not necessary.

Photo by https://www.giuseppemaccario.com/it/wp-content/uploads/2021/10/Continuous-Deployment-con-GitHub-Actions.png

I found this library perfect for testing Github Actions: act.

This library is very useful and easy to use, you can run locally your Github Actions and you have fast feedback on your workflows.

How does it work?

Act simulates the actions we would like to perform in the container of our Github Actions.
It creates a container capable of performing all the steps by properly simulating all the steps.
So we can see all the steps of the Github Actions and their results through simple instruction.

Installation

If you are using Homebrew (Linux, macOS) you can launch this command from your CLI:

brew install act

If you are not using Homebrew I recommend checking the Installation section inside the README file of the project because there are many ways and options to add it.

How to use it

To run the tool you need to write into your CLI:

act

This command runs the default (`push`) event.
When you run for the first time act, it will ask you to choose an image to be used as default and it will save that information inside the file ~/.actrc that contains configuration flags.

If you want to run a specific event you can launch:

act pull_request

For the specific event, I mean Github Events: https://docs.github.com/en/developers/webhooks-and-events/events/github-event-types

To run a specific job you can launch:

act -j your_job

You can also launch command in dry mode like this:

act -n

Environment variables and Secret variables

Secrets and environment variables saved in GitHub can’t be used by act, but you can pass them and define them locally.

Secrets

act -s KEY=VALUE — To pass secret from CLI
act — secret-file my.secrets — load secrets values from local.secrets file.

Environment variables

act -n KEY=VALUE — To pass environment variable from CLI
act — env-file my.env — load environment variables from local.env file.

Use Case

I have used act many times in these months because I created many Github actions for my projects.
Every time that I change something I tried the action with act.

So, for me, it’s better to test it locally to save a lot of time.
The process could be:
- create your first Github Actions
- launch act to test changes
- improve or fix your Github Actions
- launch act to test changes

And then you can iterate until you are satisfied with your Github Action.

Example

I have created a simple example to test act and you can find it following this link: https://github.com/AlessandroMinoccheri/act-example

It’s a simple example to test act and it took me 2 minutes to install and launch act.
It’s very useful to see the output of your GitHub Actions to understand if it’s all ok or not.

Limit

There are a few limitations by using act (https://github.com/nektos/act#known-issues):
- Non-Linux Runners: act can works for Linux runners, not for the others, but it’s a Docker limitation on your workstation.
You can work around this by setting DOCKER_HOST before running act, with e.g:

export DOCKER_HOST=$(docker context inspect — format ‘{{.Endpoints.docker.Host}}’)

- Default images do not contain intentionally all the tools that GitHub Actions offers by default in their runners.

Conclusion

In my opinion, act can save you a lot of time to test your Github Actions without launching them every time.
It’s very easy and fast to use.
Usually, when you are running act and all it’s fine your Github Actions will not have problems.