nhorne

I’ve always liked the idea of running GitHub Actions locally. Being able to test a workflow without committing changes, pushing them to GitHub, and waiting for a remote runner seemed like an excellent way to make development faster and debugging CI less frustrating.
Some time ago, I came across Act, a tool that does just that. I thought it was a great idea. Unfortunately, my experience trying to use it was rather less successful: I managed to get it running only once on my Mac laptop, but I couldn’t even get it installed on my Linux desktop.
I had hoped to be able to work out what was wrong and get Act to work, but I couldn’t. And so App::Actions was born.
Full disclosure: I also had help. I worked with FreeBuff and Claude during development, using them as part of the process of turning the initial idea into a working application. If you don’t like the use of AI in software development, stop reading now.
The result is a Perl distribution that runs GitHub Actions workflows locally using Docker.

What does App::Actions do?

The aim is straightforward: take a workflow defined in the familiar .github/workflows/ directory and run it on your own computer.
App::Actions reads and expands workflow definitions, works out what needs to run, and uses Docker to execute the jobs and their steps. It also handles expressions in workflows, job dependencies, and matrix jobs, including running matrix instances in parallel.
I’ve included command-line tools for running workflows and checking whether Docker is ready to run them:
• action-run runs a GitHub Actions workflow locally.
• action-run-smoke checks whether Docker can run an App::Actions workflow.
Testing across different Perl versions and operating systems has been particularly valuable. Something that works on one machine can fail on another for reasons that aren’t immediately obvious. That’s part of the challenge of producing a distribution that other people can install and use, rather than a script that happens to work on its author's computer.
I’m pleased that App::Actions is now working well.

Try it for yourself

App::Actions is available on CPAN, so you can install it using cpanm App::Actions
You’ll need Docker available and working on your machine. Once installed, consult the documentation for details of the supported workflow features and command-line options.
As with other local runners, App::Actions is intended to help with development and debugging; a local run should not automatically be taken as proof that every aspect of a workflow will behave identically on GitHub-hosted runners