Run GitHub Actions Locally with Act

If you've ever been stuck in the dreaded "commit-push-wait-for-CI-fail" loop, you know the pain. You make a small change, push it, wait for the GitHub Actions runner to spin up, only to find a linting error or a failed test. It's a cycle that eats up time and breaks your flow. What if you could just run those workflows on your machine first?

That's exactly what act does. It's a command-line tool that lets you run your GitHub Actions workflows locally, right on your computer, before you ever push a commit. Think of it as a local simulator for your CI/CD pipeline.

What It Does

In simple terms, act reads your .github/workflows/ YAML files, creates a Docker container (or uses an existing image) that matches the GitHub Actions runner environment, and executes your jobs and steps inside it. It parses your workflow, sets up the virtual environment, and runs through the steps just like GitHub's servers would. You get immediate feedback on whether your workflow passes or fails, without touching the remote repository.

Why It's Cool

The immediate benefit is obvious: faster feedback. But the real magic is in the developer experience it enables.

Debugging becomes trivial. When a step fails, you're not staring at remote logs; you're on your machine. You can inspect the container, check file states, and run commands interactively to figure out the root cause. You can also run specific jobs or even single steps, which is perfect for testing a complex workflow piece by piece.

It's also a safer sandbox for experimentation. Want to tweak your workflow syntax or try a new action? Test it locally without cluttering your commit history or consuming your GitHub Actions minutes. For open-source maintainers or teams, it means you can prototype and verify workflow changes in a pull request more confidently.

The tool is clever in its simplicity. It uses the official GitHub Actions runner images as a base, so the environment is as close as possible to the real thing. It also supports most of the core workflow syntax and popular actions, making it surprisingly capable for day-to-day use.

How to Try It

Getting started is straightforward. act is a Go binary, so you can install it via common package managers.

On macOS:

brew install act

On Windows:

choco install act

On Linux: Check the Installation guide for options like using a package manager or downloading the binary directly.

Once installed, navigate to your Git repository containing a .github/workflows file and simply run:

act

To run a specific workflow or job, you can use flags like -j <job_name>. The first run will prompt you to choose a default runner image size (small, medium, large). After that, it's just a matter of running act and watching your local CI pipeline come to life.

Final Thoughts

act is one of those tools that feels like it should have always existed. It directly tackles a real, everyday friction point in modern development workflows. While it might not perfectly replicate every single edge case of the cloud environment (especially secrets or environment-specific contexts), it gets 95% of the way there for most common workflows.

It won't replace running your final checks on the official runners, but it absolutely makes developing and debugging your CI/CD process faster and less frustrating. Next time you're about to push just to "see if CI passes," give act a try. It might just save you a few cycles.

Follow for more cool projects: @githubprojects