1

Testing GitHub Actions Locally with act

Ahmed Ejaz edited this page 2025-10-04 19:20:24 +05:00

Table of Contents

• 🧪 Testing GitHub Actions Locally with act
• 🧰 Prerequisites
• ⚙️ Secrets Setup
• ▶️ Running a Specific Workflow Locally
• 🧩 Tips

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

🧪 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

Home

Development environment setup

• Learning Rails
• Getting started
• Ubuntu
• Debian
• Fedora
• OS X
• Windows
• Docker

Contributing

• Pipeline development process
• Bug severity
• Feature template (epic)
• Internationalisation (i18n)
• Dependency updates

Development

• Developer Guidelines
• The process of review, test, merge and deploy
• Making a great commit
• Making a great pull request
• Code Conventions
• Database migrations
• Testing and Rspec Tips
• Testing GitHub Actions Locally with act
• Automated Testing Gotchas
• Rubocop
• Angular and OFN
• Feature toggles
• Stimulus and Turbo

Testing

• Testing process
• OFN Testing Documentation (Handbooks)
• Continuous Integration
• Parallelized test suite with knapsack
• Karma

Releasing

• Releasing
• Patch Releases

Specific features

• Sales Tax
• Product amounts units
• Stripe
• Maps

Data and APIs

• API documentation
• Authentication
• Integration & API
• Data migration
• Data model diagram (ERD)
• Stripe
• DFC Guide

Instance-specific configuration

• Locale and sample data
• Troubleshooting your instance

External services

• Setting up Stripe on an OFN instance
• Skylight setup

Design

• Design styleguide: colors and shadows
• Design styleguide: fonts and text styles
• Design styleguide: size and spacing
• Design styleguide: icons
• Design styleguide: links and buttons
• Design styleguide: navigation and menus
• Design styleguide: tables
• Design tools