Run GitHub Actions Locally with Act
Learn how to use act to run GitHub Actions on your local machine, saving time and improving development efficiency.
Have you ever had to push code to GitHub just to test a workflow that doesn’t work as expected? Or wait minutes for CI to rerun after every small change? 🤔
In this post, I’ll introduce act - a tool that lets you run GitHub Actions right on your local machine, instead of waiting for GitHub to process them remotely.
Why Run GitHub Actions Locally?#
Imagine you’re fixing a CI/CD workflow. The current process usually is:
- Edit the workflow file
- Commit and push code
- Wait for GitHub Actions to run (can take several minutes)
- See an error occur
- Go back to step 1
This is like having to email your colleague every time you want to fix a sentence in a document, instead of editing it directly. Very time-consuming and inefficient.
act solves this problem by:
- Fast Feedback - Run workflows instantly on your machine, no push needed
- Local Task Runner - Replace Makefile with GitHub Actions, leveraging existing workflow structure
- Reduced Dependency - No internet connection needed when actions and images are cached
How Does Act Work?#
Think of GitHub Actions as a factory. When you push code, GitHub will:
- Read workflow files from
.github/workflows/ - Determine which actions need to run
- Pull or build Docker images accordingly
- Run each action in a container
- Configure environment variables and filesystem to match GitHub
act does exactly the same thing, but on your machine instead of GitHub’s servers:
Installing Act#
Prerequisites#
act requires Docker to run workflows in containers. If you don’t need container isolation (e.g., running windows/macOS jobs directly on your machine), you can skip Docker.
- macOS: Install Docker Desktop for Mac
- Windows: Install Docker Desktop for Windows
- Linux: Install Docker Engine
Quick Installation#
Method 1: Homebrew (macOS & Linux)
brew install actbashMethod 2: Bash script (all platforms)
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bashbashMethod 3: GitHub CLI extension
gh extension install https://github.com/nektos/gh-actbashMethod 4: Direct download
Download from GitHub releases ↗ and add to PATH.
[!TIP] Verify installation:
bashact --version
Basic Act Usage#
Run Default Workflow#
By default, act runs all workflows with event push:
actbashRun with Specific Event#
act pull_request
act schedule
act workflow_dispatchbashList Workflows#
act -l pull_requestbashRun Specific Workflow#
act -W .github/workflows/checks.ymlbashRun Specific Job#
act -j testbashConfiguring Secrets and Variables#
Using Secrets#
GitHub automatically provides GITHUB_TOKEN when running workflows on the server. When running locally, you need to provide it:
act -s MY_SECRET=my-value
# Method 2: Use environment variable (recommended)
act -s MY_SECRET
# Method 3: Auto-get token from GitHub CLI
act -s GITHUB_TOKEN="$(gh auth token)"
# Method 4: Load from file
act --secret-file .secretsbash[!WARNING] When entering sensitive data in terminal, it may be saved to shell history. Use method 2 or 3 for better security.
Using Repository Variables#
act --var VARIABLE=some-value
act --var-file .envbash.env File Format#
Format matches Ruby dotenv:
MY_ENV='value'
PRIV_KEY="---...\nrandom text\n...---"
JSON="{\n\"name\": \"value\"\n}"
SOME_VAR=SOME_VALUEbashSkipping Jobs and Steps Locally#
Skip Jobs#
Use custom event property:
on: push
jobs:
deploy:
if: ${{ !github.event.act }} # skip when running locally
runs-on: ubuntu-latest
steps:
- run: echo "Deploy step"yamlCreate event.json:
{
"act": true
}jsonRun with:
act -e event.jsonbashSkip Steps#
act provides environment variable ACT:
- name: Notify Slack
if: ${{ !env.ACT }} # skip when running locally
run: |
curl -X POST $SLACK_WEBHOOKyamlMatrix and Advanced Features#
Run Matrix Subset#
If workflow has matrix with multiple values:
strategy:
matrix:
node: [14, 16, 18]
os: [ubuntu-latest, macos-latest]yamlOnly run with node 18:
act push --matrix node:18bashOnly run node 18 and ubuntu:
act push --matrix node:18 --matrix os:ubuntu-latestbashAction Offline Mode#
Speed up and run offline when cached:
act --action-offline-modebashBenefits:
- Don’t pull existing images
- Works offline when cached
- Avoid GitHub rate limits
- Save time with poor connection
.actrc Configuration File#
To avoid typing flags every time, create .actrc:
--container-architecture=linux/amd64
--action-offline-mode
-e event.jsonbashIssues and Limitations#
Apple Silicon (M1/M2/M3)#
If using Apple M-series chip, you may encounter architecture issues:
act --container-architecture linux/amd64bashRunner Images#
act uses different Docker images than GitHub runners. Some tools may not work:
ubuntu-latest→node:16-buster-slim(light) orcatthehacker/ubuntu:act-latest(medium)- For environment matching GitHub exactly, use
nektos/act-environments-ubuntu:18.04
Unsupported Features#
Some GitHub Actions features are not supported:
- Docker context
- Some complex matrix configurations
- Some GitHub Actions specific features
Practical Examples#
Simple Workflow#
name: Test
on: push
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: '18'
- name: Install
run: npm install
- name: Test
run: npm testyamlRun locally:
actbashWorkflow with Secrets#
name: Deploy
on: push
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Deploy to production
run: |
curl -X POST ${{ secrets.DEPLOY_URL }}yamlRun locally:
act -s DEPLOY_URLbashComparison with GitHub Actions#
| Feature | GitHub Actions | act (local) |
|---|---|---|
| Feedback speed | Slow (must push) | Fast (run immediately) |
| Resource cost | GitHub account quota | Your local machine |
| Environment | Exact | Nearly exact |
| Offline | No | Yes (with offline mode) |
| Matrix testing | Time-consuming | Fast (run subset) |
| Secrets | Managed on GitHub | Manual passing |
Conclusion#
act is an invaluable tool for any developer using GitHub Actions. It helps:
- Speed up development and workflow debugging
- Reduce dependency on GitHub infrastructure
- Test workflows before pushing
- Leverage GitHub Actions as a local task runner
[!TIP] Best practice: Always test workflows with act before pushing, especially when modifying complex workflow structures.