Testing GitHub Actions Locally with act

🧪 Testing GitHub Actions Locally with act

act allows you to run GitHub Actions locally using Docker — exactly as they run on GitHub’s infrastructure. This helps debug workflows quickly without committing or pushing code.

🧰 Prerequisites

Before running locally, make sure you have:

• Docker — running and available in your environment
• act — installed globally

brew install act           # macOS
scoop install act          # Windows
sudo apt install act       # Linux (via apt repository)

⚙️ Secrets Setup

act cannot read GitHub secrets automatically, so you’ll need a local file to define them.

Create a .secrets file by copying the .secrets.example.

cp .secrets.example .secrets

▶️ Running a Specific Workflow Locally

You can trigger a workflow manually using act:

act <event_name> -e <path_to_event_json_payload> -W <path_to_workflow_yml>

For example:

act pull_request \
  -e .github/test-events/dependabot-pr.json \
  -W .github/workflows/move-dependency-pr-to-code-review.yml

Arguments explained:

• pull_request → GitHub event type you want to simulate
• e → path to a JSON file containing event payload (mock PR data)
• W → path to a specific workflow file to run

🧩 Tips

act uses Docker images to mimic GitHub runners. Use a larger image if you need a full Ubuntu environment:

act -P ubuntu-latest=catthehacker/ubuntu:act-latest

To print detailed logs:

act -v

You can list all available jobs in your workflow:

act -l