How to run GitHub Actions workflows locally?
Github ActionsGithub Actions Problem Overview
I am planning to move our Travis CI build to GitHub Actions using Docker for our per-commit testing.
Can I reproducibly run these new GitHub Actions workflows locally? Is there a generic way to run any GitHub Actions workflow locally?
Github Actions Solutions
Solution 1 - Github Actions
There are tools like the already-mentioned act, but they are not perfect.
You are not alone with this issue. Similar problems are:
- how to test Jenkins builds locally
- how to test Circle CI builds locally
- how to test XXXX builds locally
And my solution for these problems is:
- avoid functionalities provided by your CI tools (GitHub Actions, Gitlab CI, etc)
- write as much as possible in CI-agnostic way (BASH scripts, PowerShell scripts, Gradle scripts, NPM scripts, Dockerfiles, Ansible scripts - anything you know)
- invoke those scripts from your CI tool. In GitHub actions:
run: your command to run
Solution 2 - Github Actions
You can use nektos/act which supports yaml syntax since 0.2.0 (prerelease).
Check out their latest release.
Solution 3 - Github Actions
One way to test Github actions is to create a private repo, and iterate the actions conf there. So you can avoid polluting the actual repo with broken commits.
I know, this is not a direct answer to the question - this is not a local way. But this didn’t occur to me at first and I think this could be enough for many use cases.
Solution 4 - Github Actions
your best bet is https://github.com/nektos/act however (prior to 0.2.0) it doesn't support yaml syntax yet, though there is a lot of interest aka: https://github.com/nektos/act/issues/80 https://github.com/nektos/act/issues/76 and https://github.com/nektos/act/issues/74
Gitlab has gitlab-runner exec docker job-name but that's Gitlab :)
Solution 5 - Github Actions
I'm assuming that you want to run the action locally because it is failing, and you want to debug it. If so, another alternative (which doesn't require running locally) is to use action-tmate to SSH into the machine running your action. From there, you can view logs, run commands, etc to work out what the problem is.
To get started:
- In your workflow yaml file, after the step that is failing, put a new step as follows:
- name: Setup tmate session
if: ${{ failure() }}
uses: mxschmitt/action-tmate@v3
-
Push the changes to GitHub and rerun the action.
-
Wait for it to fail again - this time, instead of stopping the workflow, a tmate session will be opened, and the SSH details will be printed in the workflow console.
-
Connect via SSH from your own machine, and now you have full access to the runner machine.
Solution 6 - Github Actions
To add on top of what's being said by @iirekm and @riQQ, in order to stay CI-agnostic and have some orchestration features, you could abstract your steps with Task and then call your tasks from your Github Actions or any other CI/CD. That way you also get the benefit of being able run everything locally.
Solution 7 - Github Actions
with the use of docker containers, this tool called act, can be found here, https://github.com/nektos/act You can run all your github actions locally inside a docker container. NB: act builds all necessary containers for actions to run. all you do is follow the documentation on how to use the tool