Running GitHub Actions Locally with act: ‘Lightning Fast’ Pipeline Debugging Without Pushing Code – ITFROMZERO

Table of Contents

The “Fix CI/CD” Nightmare at 2 AM

We’ve all been there: production goes down in the middle of the night. You rush to patch the code, push it, and pray for a green checkmark on GitHub Actions. But instead, you get a red X. The issue isn’t even your logic; it’s just a stray space in a YAML file or a missing Environment Variable.

Then begins the cycle of doom. Edit YAML, push code, wait 3-5 minutes for the Runner to start. Red again. Fix, push. After two hours of struggling, your Git history looks like a battlefield with 20 commits like: “fix ci”, “fix ci again”, “hope this works”… It’s a massive waste of time and incredibly frustrating!

Why is Debugging GitHub Actions So Exhausting?

The most painful part of Cloud CI/CD is the slow feedback loop. Every tiny change forces you to push code to GitHub’s servers. You’re essentially flying blind inside the GitHub container unless you manually insert dozens of ls -la or echo $VAR commands to inspect the logs.

I once spent an entire morning pushing the same line—chmod +x deploy.sh—simply because I forgot to set execution permissions. My colleagues could only shake their heads looking at the commit history. If I had known how to run the workflow locally back then, I would have saved at least 3 hours and a chunk of my free GitHub Actions quota.

Stop-gap Solutions (and Their Weaknesses)

Running scripts manually: You copy commands from YAML to your local terminal. The result? Your machine is macOS/Windows, while the Runner is Ubuntu. It fails on GitHub due to Node version mismatches or missing system libraries.
Using ‘trash’ branches for testing: This keeps your main branch clean, but you still have to wait for the Runner to spin up. Waiting 5 minutes just to find out you missed a double quote is truly painful.

The Savior: Bringing GitHub Actions Local with “act”

To end this waste of time, use act. This tool uses Docker to spin up a local environment almost identical to a GitHub Runner. It reads your workflow files, downloads the images, and runs your jobs in seconds.

Install act in 30 Seconds

Installing act is extremely simple. Depending on your operating system, use the following commands:

# macOS (Homebrew)
brew install nektos/tap/act

# Windows (Winget)
winget install nektos.act

# Linux
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Note: You must have Docker installed as it is the core engine act uses to create job environments.

Triggering Your First Workflow

Simply navigate to your project’s root directory (where the .github/ folder is) and run:

act

By default, this command runs jobs triggered by push events. To run jobs for other events or specify a particular job, use:

# Run pull_request event
act pull_request

# List available jobs
act -l

# Run only the job named 'build-test'
act -j build-test

Secret Management Made Easy

Instead of configuring Secrets via the GitHub web interface, you can just create a .env file locally:

act --secret-file .env

The .env file content is standard:

DOCKER_PASSWORD=my_secret_key
AWS_ACCESS_KEY_ID=AKIAXXXXXXXXXXXX

Important: Always add .env to your .gitignore to avoid accidentally pushing your secrets and compromising your machine’s security.

“Battle-Tested” Tips for Using act Effectively

Despite its power, act has some differences from the actual cloud environment. Keep these three points in mind:

1. Don’t Go Overboard with Large Images

When you first run it, act will ask you to choose an Image (Small, Medium, Large). The default GitHub image is over 15GB. If disk space is tight, go with Medium (~500MB). The Small version often lacks git or curl, which can lead to confusing errors.

2. Handling Docker-in-Docker

If your workflow includes docker build commands, you need to share the Docker socket from your host to the act container using a flag:

act --container-daemon-socket /var/run/docker.sock

3. Verifying Artifacts

act doesn’t automatically upload build files (Artifacts) to the cloud. To inspect the output after a run, use --artifact-server-path to save files directly to a local folder.

Conclusion: Master Your CI/CD, Don’t Let It Master You

Using act isn’t just about saving time. It helps you build a professional DevOps mindset: test fast, fail early, and fix on the spot. Don’t let silly syntax errors ruin your sleep or turn your Git history into a mess.

Try installing act today—you’ll find that debugging CI/CD can be just as satisfying as writing code!