How to run GitHub Actions in local with Act
GitHub Actions is a powerful tool, you can run tests, build your app, deploy it, even mining bitcoins 😔
When you are creating an action or workflow in GitHub Actions, it is very common the needing of test it, check if all works as you need and if something is not correct, fix it, in other works as other software GitHub Actions need to be iterated.
Doing it in GitHub have disadvantages:
- Waste running time: even if you are using a free plan you have a 2000 minutes per month limit
- Fill your repository history with “trash” commit: As the action definition is in the repo, every change is a new commit, if you are testing something that is very common to fill your repo history with the commits of every change. You can squash these commits into one, but is an extra step
- Is slow
ACT comes to help us, this tool allows us to run GitHub Actions on our local computer.
It creates an environment equal to GitHub provides, uses Docker images to run the actions, the environment variables and filesystem are all configured to match what GitHub provides.
Act is available for Linux, Windows and MacOS, the installation instructions (and dependencies) depend on your OS, I’m going to focus on Ubuntu, but you can check the official docs to know how to install in your OS.
In Ubuntu, you need Go 1.16+ as a dependency and run
go install github.com/nektos/act@latest
Is very useful to add the Go bin path to your PATH For example, if you are using zsh as shell
echo "export PATH=$PATH;~/go/bin/" >> ~/.zshrc
Running your action
Running an action on your computer is simple as go to your repo root folder and run:
In the first run, Act will ask you to choose the default image to run the action. The image to choose depends on your action, but I recommend you to choose, the medium image, because the micro image for example can’t install Python
If your action needs “secrets” will fail. We must set the secrets and that is easy as pass an argument to act
act -s GITHUB_TOKEN=<your_token> -s OTHER_SECRET=<value>
It’s important to bear in mind that GitHub always injects the
GITHUB_TOKEN secret, but in our local environment, we must provide the value.
If your action needs this value (for example, after build, deploy to GHPages) you must provide it.
To create a token in GitHub you only need to navigate to Settings > Developer settings > Personal access tokens or just https://github.com/settings/tokens
Dispatching custom events
By default, act runs the “on: push” configured action in your workflow file, but maybe you want to run another workflow depending on other triggers, and you can, only need to pass the event name as an argument
act pull_request act workflow_dispatch act release ...
Use a specific workflow
Sometimes you have more than workflow files, usually, they don’t run on the same dispatcher, but anyway, you can set the workflow file to use.
act -W <path to workflow file>
Listing the actions
act -l or
act release -l you can list the action that will run
Sometimes can be interesting to see the action’s dependency tree, using the
-g flag you will get an exit like that
Run a specific job
If you want to test a specific job into the workflow you can pass the job name using
-j argument, for example
act -j deploy
There are more flags. You can check the full list here
Act can login to private GitHub Enterprise servers as simple as add
--github-instance <your-company-ghe-server> in the command
Act it’s a wonderful tool to run GH Action in local when you are creating or iterating it, avoiding using the real repo to test it. But Act is something more, you can also use it as a local task runner using all the power, and the actions in the GitHub Actions marketplace to create your local task, and this task can easily move to the cloud if you need it.