Testing and iterating on GitHub Actions workflows can be slow. Every change usually means a commit, a push, and waiting for GitHub runners—frustrating for API developers and backend engineers who need to debug or rapidly prototype their CI/CD pipelines. What if you could run and debug your workflows locally, getting instant feedback before pushing to GitHub?
This guide explains how to use act, a powerful open-source CLI tool that runs GitHub Actions locally using Docker. You'll learn how act works, how to install it, practical usage tips, limitations, and how tools like Apidog can enhance your workflow.
Why Test GitHub Actions Locally?
Local testing with act offers API and backend teams the following advantages:
- Instant Feedback: Skip the commit-push-wait-debug cycle. See workflow results in seconds, not minutes.
- Consistent Task Runner: Use your GitHub Actions YAML files as universal build/test/lint scripts—run them locally and in CI, ensuring parity between environments.
- Offline Support: Develop and test workflow syntax even when disconnected from the internet (after initial setup).
- Cost Efficiency: Save GitHub Actions runner minutes and avoid hitting usage caps during heavy development.
- Advanced Debugging: Inspect containers directly, mount volumes, inject extra logging, and use familiar local tools for troubleshooting.
💡 Looking for an API platform that generates beautiful API documentation and boosts team productivity? Try Apidog. It streamlines API testing and collaboration for developers, providing an all-in-one solution at a cost lower than Postman. 
How Does act Simulate GitHub Actions?
act leverages Docker to emulate the GitHub Actions runner environment, running each workflow job in an isolated container. Here’s how it works:
- Workflow Discovery: Scans
.github/workflows/for YAML files in your repository. - Event Simulation: By default, simulates a
pushevent, but can trigger others (e.g.,pull_request,workflow_dispatch). - Dependency Resolution: Understands job dependencies (
needs:) to run jobs in order. - Docker Image Selection: Maps the
runs-on:field to Docker images representing the runner environment. - Container Execution: Runs each job step in a container, injecting environment variables, mounting your repo, and streaming logs to your terminal.
Example:
If your workflow runs on ubuntu-latest, act will pull a compatible Ubuntu Docker image, mount your repo at /github/workspace, and execute steps as they would run on GitHub.
Prerequisite: Install Docker
act depends on Docker. Ensure Docker is installed and running:
- macOS/Windows: Docker Desktop
- Linux: Install via your package manager. Add your user to the
dockergroup for non-root access.
Verify Docker with:
docker run hello-world
How to Install act
Choose the method that best fits your OS and workflow:
1. Homebrew (macOS/Linux)
brew install act
For the cutting-edge version:
brew install act --HEAD
2. GitHub CLI Extension
gh extension install nektos/gh-act
gh act # Usage
3. Windows Package Managers
- Chocolatey:
choco install act-cli - Scoop:
scoop install act - WinGet:
winget install nektos.act
4. Linux Script Installer
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
Review the script for security before running.
5. Other Package Managers
Check the official docs for Arch, Fedora COPR, MacPorts, Nix, etc.
Verify Installation:
act --version
# or
gh act --version
Choosing a Runner Image in act
The first time you run act, you'll be asked to pick a default Docker image for the runner:
- Micro: Node.js only (~200MB)
- Medium: Common tools (~500MB) – Recommended
- Large: Full GitHub runner clone (>17GB)
Tip: Start with Medium for most workflows. Upgrade to Large only if you hit missing tool errors.
act stores your choice in ~/.actrc. You can change it anytime.
Core Usage: Running Workflows Locally
Navigate to your project root (with the .github folder) and try:
1. Run Default Push Event
act
# or
gh act
2. List All Workflows and Jobs
act -l
Example output:
Stage Job ID Job name Workflow name Workflow file Events
0 build Build CI Pipeline ci.yaml push
1 test Test CI Pipeline ci.yaml push
1 lint Lint Code Quality codeql.yaml push,pull_request
3. Run a Specific Job Only
act -j build
4. Simulate Different Events
act pull_request
act workflow_dispatch
act schedule
act release -e event.json # with a payload file
5. Pass Inputs to workflow_dispatch
act workflow_dispatch --input environment=staging
6. Manage Secrets and Environment Variables
- Interactive prompt:
act -s MY_SECRET_TOKEN - Secrets file:
Create.secrets:
Run:MY_SECRET=your_valueact --secret-file .secrets - Env file:
act --env-file .env_vars
Always add secrets files to .gitignore.
Customizing Runner Environments
1. Specify Custom Images per Platform
If you need a different Docker image for a specific runs-on:, use -P:
act -P ubuntu-22.04=ghcr.io/catthehacker/ubuntu:full-22.04
act -P ubuntu-latest=node:18-bullseye
2. Use Local Images & Offline Mode
act --pull=false
Prevents automatic pulling of images.
3. Native Execution (macOS/Windows)
To run jobs directly on your host OS (not in Docker):
act -P macos-latest=-self-hosted
act -P windows-latest=-self-hosted
Caution: This bypasses Docker isolation. Use carefully.
act Limitations and Best Practices
While act is excellent for rapid iteration, know its limits:
- Not a Perfect Match: The local Docker environment may differ from GitHub’s runners (networking, installed tools, OS services).
- Secrets: Must be provided manually; act does not fetch from GitHub.
- Concurrency: Jobs typically run sequentially unless parallelism is configured.
- Platform Coverage: Linux jobs work everywhere, but macOS and Windows jobs require matching hosts or native execution.
- Some Features Differ: Actions like caching or service containers may require tweaks.
Best Practice: Use act for development, syntax, and logic checks. For production and deployment workflows, always validate on GitHub itself to avoid surprises.
Power Up Your API Workflows with Apidog
Efficient CI/CD is only part of high-quality API development. Tools like Apidog help API-focused teams:
- Generate beautiful API documentation
- Collaborate on API design, testing, and automation
- Replace siloed tools (like Postman) with an all-in-one, cost-effective platform
Apidog integrates smoothly into local and CI/CD pipelines, streamlining workflows for backend and QA engineers.
Conclusion
Running GitHub Actions locally with act transforms your workflow:
- Faster Debugging: Rapid feedback and easier troubleshooting.
- Reliable Pipelines: Consistent local and CI environments.
- Developer Focus: Spend less time waiting, more time improving your APIs.
Combine act with professional API tools like Apidog for even smoother API lifecycle management.
