blog.dopana

Back

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:

  1. Edit the workflow file
  2. Commit and push code
  3. Wait for GitHub Actions to run (can take several minutes)
  4. See an error occur
  5. 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:

  1. Read workflow files from .github/workflows/
  2. Determine which actions need to run
  3. Pull or build Docker images accordingly
  4. Run each action in a container
  5. Configure environment variables and filesystem to match GitHub

act does exactly the same thing, but on your machine instead of GitHub’s servers:

You run actRead workflow filesDetermine actions to runDocker APIPull/Build imagesRun containersConfigure env & filesystemExecute workflow

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)

Homebrew
brew install act
bash

Method 2: Bash script (all platforms)

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
bash

Method 3: GitHub CLI extension

gh extension install https://github.com/nektos/gh-act
bash

Method 4: Direct download

Download from GitHub releases ↗ and add to PATH.

[!TIP] Verify installation:

act --version
bash

Basic Act Usage#

Run Default Workflow#

By default, act runs all workflows with event push:

act
bash

Run with Specific Event#

act pull_request

act schedule

act workflow_dispatch
bash

List Workflows#

act -l pull_request
bash

Run Specific Workflow#

act -W .github/workflows/checks.yml
bash

Run Specific Job#

act -j test
bash

Configuring 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 .secrets
bash

[!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 .env
bash

.env File Format#

Format matches Ruby dotenv:

MY_ENV='value'
PRIV_KEY="---...\nrandom text\n...---"
JSON="{\n\"name\": \"value\"\n}"
SOME_VAR=SOME_VALUE
bash

Skipping Jobs and Steps Locally#

Skip Jobs#

Use custom event property:

workflow.yml
on: push
jobs:
  deploy:
    if: ${{ !github.event.act }} # skip when running locally
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploy step"
yaml

Create event.json:

event.json
{
  "act": true
}
json

Run with:

act -e event.json
bash

Skip Steps#

act provides environment variable ACT:

workflow.yml
- name: Notify Slack
  if: ${{ !env.ACT }} # skip when running locally
  run: |
    curl -X POST $SLACK_WEBHOOK
yaml

Matrix and Advanced Features#

Run Matrix Subset#

If workflow has matrix with multiple values:

workflow.yml
strategy:
  matrix:
    node: [14, 16, 18]
    os: [ubuntu-latest, macos-latest]
yaml

Only run with node 18:

act push --matrix node:18
bash

Only run node 18 and ubuntu:

act push --matrix node:18 --matrix os:ubuntu-latest
bash

Action Offline Mode#

Speed up and run offline when cached:

act --action-offline-mode
bash

Benefits:

  • 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:

.actrc
--container-architecture=linux/amd64
--action-offline-mode
-e event.json
bash

Issues and Limitations#

Apple Silicon (M1/M2/M3)#

If using Apple M-series chip, you may encounter architecture issues:

act --container-architecture linux/amd64
bash

Runner Images#

act uses different Docker images than GitHub runners. Some tools may not work:

  • ubuntu-latest → node:16-buster-slim (light) or catthehacker/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#

.github/workflows/test.yml
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 test
yaml

Run locally:

act
bash

Workflow with Secrets#

.github/workflows/deploy.yml
name: Deploy
on: push
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to production
        run: |
          curl -X POST ${{ secrets.DEPLOY_URL }}
yaml

Run locally:

act -s DEPLOY_URL
bash

Comparison with GitHub Actions#

FeatureGitHub Actionsact (local)
Feedback speedSlow (must push)Fast (run immediately)
Resource costGitHub account quotaYour local machine
EnvironmentExactNearly exact
OfflineNoYes (with offline mode)
Matrix testingTime-consumingFast (run subset)
SecretsManaged on GitHubManual 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.

References#