GitHub Actions Local Runner (act) CLI Guide

Installation

# macOS using Homebrew
brew install act

# Windows using Chocolatey
choco install act-cli

# Using curl (Linux/macOS)
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Basic Commands

# List all available actions in your repository
act -l

# Run all workflows
act

# Run a specific workflow
act workflow_dispatch

# Run a specific job
act -j job_id

# Run a specific event
act push

Advanced Usage

# Run with verbose logging
act -v

# Run with different environment
act -P ubuntu-latest=nectos/act-environments-ubuntu:18.04

# Run with secrets
act -s MY_SECRET=value

# Run with specific artifact directory
act --artifact-server-path /tmp/artifacts

# Run with Docker bind mounts
act -b

# Run without pulling images (use locally cached ones)
act --pull=false

# Run with specific GitHub token
act -s GITHUB_TOKEN=your_token

# Run with specific platform
act -P ubuntu-latest=ubuntu:18.04

Environment Configuration

# List available environment images
act --list-platforms

# Use a specific runner image
act -P ubuntu-latest=catthehacker/ubuntu:act-latest

# Run with custom environment variables
act -e MY_ENV=value

# Use .secrets file
act --secret-file my.secrets

# Set working directory
act -C /path/to/repo

Event-Specific Commands

# Trigger pull request event
act pull_request

# Trigger push event
act push

# Trigger release event
act release

# Trigger schedule event
act schedule

Debugging Options

# Dry run (don't actually run actions)
act -n

# Show action debug logs
act -v

# Keep temporary containers for debugging
act --rm=false

# Show raw output
act --raw

Common Use Cases

1. Local Development Testing:

# Test specific workflow before pushing
act -W .github/workflows/specific-workflow.yml

2. CI/CD Pipeline Testing:

# Test complete pipeline
act --workflows .github/workflows/ push

3. PR Validation:

# Test PR workflows
act pull_request

Best Practices

1. Create a .actrc file in your repository root for common configurations:

-P ubuntu-latest=catthehacker/ubuntu:act-latest
-P ubuntu-18.04=catthehacker/ubuntu:act-18.04
--secret-file my.secrets

2. Use .env file for environment variables:

GITHUB_TOKEN=your_token
MY_CUSTOM_VAR=value

3. Set up local secrets in .secrets:

DOCKER_USERNAME=myuser
DOCKER_PASSWORD=mypassword

Troubleshooting

1. Permission Issues:

# Run with sudo if needed
sudo act

# Fix Docker permissions
sudo chmod 666 /var/run/docker.sock

2. Memory Issues:

# Increase Docker memory limit
act --container-options "-m 4G"

3. Network Issues:

# Run with network access
act --network host

Notes

• Always ensure Docker is running before using act
• Some actions might not work locally due to platform limitations
• GitHub Enterprise features might not be fully supported
• External services and certain GitHub APIs might not be accessible
• Consider using mock services for external dependencies

Remember to check the official act documentation for the most up-to-date information and additional features.