A Complete Guide to Using Act for Local GitHub Actions Development

What Is Act and Why Use It

Act is an open-source command-line tool that allows developers to run GitHub Actions workflows locally on their own machines. Rather than relying on GitHub's hosted runners, Act uses Docker containers to create a local execution environment that closely mirrors what GitHub provides. This means you can test, debug, and iterate on your workflows without waiting for remote execution or consuming GitHub Actions minutes.

The traditional GitHub Actions development cycle involves pushing code, waiting for workflow runs (which can take several minutes), examining logs for failures, making fixes, and repeating the process. Each iteration consumes Action minutes and generates unnecessary commit history. Act eliminates this cycle by enabling immediate local testing with the same workflow definitions you use in production.

For teams looking to optimize their CI/CD workflows, our /services/devops/ experts can help you implement best practices for local testing and continuous integration.

Key Benefits

• Rapid feedback - Workflows execute in seconds on your local machine
• Easier debugging - Inspect logs, examine container states, and interact directly
• Offline development - Work on workflows without an internet connection
• Cost savings - Reduce GitHub Actions minute consumption

When you run Act, it reads your workflow files from .github/workflows/ and parses them to understand jobs, steps, and actions required. Act then uses Docker to create containers matching GitHub's runner environments--typically Ubuntu-based containers with common development tools. Each job runs in its own container, maintaining the same isolation guarantees as GitHub's runners. Environment variables, filesystem paths, and GitHub-specific contexts are all simulated to match GitHub's behavior as closely as possible, as documented in the Nektos Act Official Documentation.

Installing Act on Your System

Act supports multiple installation methods regardless of your operating system or preferred package manager.

Homebrew (macOS and Linux)

brew install act

This method handles PATH configuration automatically and provides easy upgrade paths through Homebrew's standard update commands.

npm or Yarn

npm install -g @nektos/act-commands
# or
yarn global add @nektos/act-commands

Docker

docker run nektos/act-act:latest --version

Manual Binary Installation

Download pre-built binaries from the official GitHub releases page, then:

chmod +x act
sudo mv act /usr/local/bin/

Verify Installation

act --version
act --list

The --list command shows all workflows in your repository without executing them, useful for understanding what Act will run before committing to execution.

How Act Works

Understanding Act's architecture helps you use it more effectively. When you run Act, it reads your workflow files from .github/workflows/ and parses them to understand the sequence of jobs, steps, and actions required. Act then uses the Docker API to create containers that match GitHub's runner environments--typically Ubuntu-based containers with common development tools pre-installed.

Each job runs in its own container, maintaining the same isolation guarantees that GitHub's runners provide. Environment variables, filesystem paths, and GitHub-specific contexts are all simulated to match GitHub's behavior as closely as possible.

Act ships with several built-in runner images of varying sizes: the Small image provides essential tools with faster pull times, the Medium image offers a balance between size and functionality, and the Large image matches GitHub's hosted runners most closely. You can also specify custom Docker images for specialized requirements using the --image flag.

Running Your First Workflow Locally

Basic Execution

cd your-repository
act

By default, Act executes all workflows triggered by push events. You'll see output similar to GitHub Actions web interface, showing each job, step, and their execution status.

Specifying Events

act pull_request # Run PR-triggered workflows
act push # Run push-triggered workflows
act workflow_dispatch # Manually triggered workflows

Running Specific Workflows

act --workflows .github/workflows/ci.yml

This is particularly useful in repositories with multiple workflows where running all of them would be time-consuming during development.

Dry Run Mode

act --dryrun

Dry run mode displays the workflow execution plan without starting containers, showing which jobs and steps would run. This performs syntax validation without executing anything, catching YAML structure issues and missing required fields before they reach your repository, as recommended in the Better Stack Community Guide.

Managing Secrets and Environment Variables

Workflows often require secrets and environment variables for operations like accessing APIs, deploying to cloud services, or connecting to databases. Act provides multiple mechanisms for supplying these sensitive values during local execution.

Using .secrets File

Create a .secrets file in your repository root:

DATABASE_URL=your-production-url
API_KEY=your-secret-key

Add .secrets to your .gitignore to prevent accidental commits. When running Act, secrets from this file are automatically available to your workflows.

Command Line Secrets

act -s DATABASE_URL="test-value" -s API_KEY="test-key"

The -s or --secret flag injects the provided secret into the workflow execution environment for quick, one-off testing.

Environment Files

act --env-file .env.test

Built-in GitHub Secrets

Act provides simulated secrets like GITHUB_TOKEN that match GitHub's behavior, so workflows relying on these values work correctly locally.

Security Note: Never commit actual production secrets. Use separate test credentials for local development, and consider using secret scanning tools to prevent accidental exposure, as outlined in the Better Stack Community Guide.

For organizations seeking comprehensive security practices in their CI/CD pipelines, our /services/web-development/ team can help implement secure secret management strategies across your development workflows.

Customizing Runner Images and Configuration

Runner Image Sizes

Act ships with different sized images: Small (minimal, faster to pull), Medium (balance of size and functionality), and Large (full-featured, closest to GitHub's runners).

Using .actrc for Persistent Config

Create .actrc in your repository for persistent configuration:

--secret-file .secrets
--env-file .env.local
--container-architecture linux/amd64
--workflows .github/workflows/*.yml

Each line represents a command-line argument that Act will use by default, eliminating repetitive flag typing and ensuring consistent behavior across team members.

Path Filtering

act --path-filter src/

Only runs workflows when files in specified paths change, significantly speeding up development in monorepos where changes to unrelated parts of the codebase shouldn't trigger all workflows.

Custom Images

act --image my-custom-runner:latest

For specialized requirements, you can specify custom Docker images. This is useful when your workflows require specific tooling, versions, or configurations not present in the default images.

Common Use Cases

Testing CI/CD Pipelines

A typical CI/CD pipeline involves multiple stages: building code, running tests, performing security scans, and deploying artifacts. With Act, you can test this entire pipeline locally:

act # Run full CI pipeline
act -j build # Run only build job
act -j deploy --shell # Interactive debug deployment

Debugging Failed Workflows

When a workflow fails, Act provides several debugging capabilities. Increase verbosity with -v for detailed step output or -vv for very verbose output including step arguments. Run a specific failing job with a shell to interactively debug:

act -v # Verbose output
act -vv # Very verbose (includes arguments)
act -j failing-job --shell # Interactive shell in container

This drops you into a shell within the job's container, where you can examine files, run commands manually, and identify the root cause of failures, as demonstrated in the LogRocket Tutorial.

Testing Matrix Strategies

act --matrix '{"os": ["ubuntu-latest"], "node-version": ["18.x"]}'

Workflows with matrix strategies benefit from local testing. Instead of waiting for GitHub's runners to execute all matrix combinations, test specific configurations rapidly.

Performance Optimization

BuildKit for Faster Builds

act --buildkit

BuildKit provides parallel builds and better caching, significantly reducing workflow execution time for Docker-based actions.

Dependency Caching

act --cache

Caches downloaded items between runs, similar to how GitHub Actions handles caching on their infrastructure.

Resource Management

act --rm # Remove containers after execution
act --container-options "--memory=4g" # Limit memory
act --jobs 1 # Limit concurrent jobs

These options help manage resource consumption, particularly on machines with limited memory or when running multiple concurrent workflows.

Parallel Execution

act --parallel

Runs independent jobs concurrently for faster execution. While jobs within a workflow run in dependency order, Act can execute independent jobs in parallel, speeding up workflows that have multiple independent stages.

Integrating Act with Development Tools

VS Code Extension

The GitHub Local Actions extension for Visual Studio Code provides a graphical interface for running Act directly from your editor. Install it from the VS Code marketplace for workflow selection from a dropdown, visual feedback on execution status, and integrated log viewing.

Pre-Commit Hook

# .pre-commit-config.yaml
- repo: https://github.com/nektos/act
 rev: v0.2.0
 hooks:
 - id: act
 stages: [push]
 files: \.github/workflows/.*

This runs Act in dry-run mode on pre-commit, catching workflow issues before they enter your repository's history.

Makefile Integration

.PHONY: test-workflows
test-workflows:
	act --workflows .github/workflows/ci.yml \
		--secret-file .secrets.test \
		--env-file .env.test

This abstraction makes it easy for team members to run workflows without memorizing complex command-line arguments. Integrate this into your DevOps workflow to ensure consistent CI/CD testing across your team. Our /services/devops/ specialists can help you implement comprehensive workflow testing and automation strategies that scale with your organization.

Troubleshooting Common Issues

Docker Permission Errors

sudo usermod -aG docker $USER
newgrp docker

If you see permission errors related to Docker, ensure your user has permission to access the Docker socket.

Out of Memory Errors

act --jobs 1
act --container-options "--memory=2g"

Large workflows or memory-intensive jobs may exhaust system memory. Reduce memory usage by limiting concurrent jobs or specifying lower memory containers.

Network Issues

act --network host

Workflows requiring network access may fail if Docker's network configuration is incorrect. Use host networking when needed.

Missing Actions or Tools

act pull # Pull latest images
act --image nektos/act-environments-ubuntu:full # Larger image

Best Practices

• Run Act whenever you modify workflow files rather than pushing and waiting for GitHub
• Keep .actrc in version control for team consistency
• Use pre-commit validation to catch issues before they affect shared repositories
• Create dedicated test secrets (never production values) for local development
• Document custom configurations or images your workflows require
• Update Act regularly for bug fixes and new features

Sources

1. Nektos Act Official Documentation - Primary reference for installation methods, architecture, and core concepts
2. Better Stack Community Guide - Best practices for local workflow testing and configuration
3. LogRocket Tutorial - Practical implementation examples and debugging strategies
4. GitHub Local Actions - VS Code Extension - Community examples and VS Code integration