Documentation/Tools/Act/ skills /act-local-testing

šŸ“– act-local-testing

Use when testing GitHub Actions workflows locally with act. Covers act CLI usage, Docker configuration, debugging workflows, and troubleshooting common issues when running workflows on your local machine.

šŸ¤– Agent Only
Allowed Tools: Read, Write, Edit, Bash, Grep, Glob

Overview

Use this skill when testing GitHub Actions workflows locally with act. This covers act CLI commands, Docker setup, debugging, and best practices for fast local iteration on CI/CD workflows.

Installation

macOS

bash
brew install act

Linux

bash
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Windows

bash
choco install act-cli
# or
scoop install act

From Source

bash
go install github.com/nektos/act@latest

Basic Usage

Run All Workflows

bash
# Run workflows triggered by push event
act

# Equivalent to
act push

Run Specific Events

bash
# Pull request event
act pull_request

# Workflow dispatch
act workflow_dispatch

# Custom event
act repository_dispatch -e event.json

Run Specific Workflows

bash
# Run specific workflow file
act -W .github/workflows/ci.yml

# Run specific job
act -j build

# Run specific workflow and job
act -W .github/workflows/deploy.yml -j production

List Available Workflows

bash
# List all workflows and jobs
act -l

# List for specific event
act pull_request -l

Validation and Dry Runs

Dry Run

bash
# Validate without executing
act --dryrun

# Show what would run
act -n

# Validate specific workflow
act --dryrun -W .github/workflows/ci.yml

Graph Visualization

bash
# Show workflow graph
act -g

# Show graph for specific event
act pull_request -g

Docker Configuration

Default Runners

Act uses Docker images to simulate GitHub's runners:

bash
# Use default images (micro - minimal)
act

# Use medium images (more tools)
act -P ubuntu-latest=catthehacker/ubuntu:act-latest

# Use large images (most compatible)
act -P ubuntu-latest=catthehacker/ubuntu:full-latest

Custom Platform Images

Create .actrc file in project root:

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

Or use command line:

bash
act -P ubuntu-latest=node:18 \
    -P ubuntu-22.04=catthehacker/ubuntu:act-22.04

Reusing Docker Containers

bash
# Reuse containers between runs (faster)
act --reuse

# Clean up after run
act --rm

Secrets Management

Using .secrets File

Create .secrets in project root:

GITHUB_TOKEN=ghp_your_token_here
NPM_TOKEN=npm_your_token_here
AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret

Add to .gitignore:

.secrets

Run with secrets:

bash
act --secret-file .secrets

Inline Secrets

bash
# Single secret
act -s GITHUB_TOKEN=ghp_token

# Multiple secrets
act -s GITHUB_TOKEN=ghp_token \
    -s NPM_TOKEN=npm_token

Environment-Specific Secrets

bash
# Development secrets
act --secret-file .secrets.dev

# Production secrets
act --secret-file .secrets.prod

Environment Variables

Setting Variables

bash
# Single variable
act --env NODE_ENV=development

# Multiple variables
act --env NODE_ENV=development \
    --env DEBUG=true

Using .env File

Create .env file:

NODE_ENV=development
DEBUG=true
LOG_LEVEL=debug

Run with env file:

bash
act --env-file .env

GitHub Context Variables

Act automatically sets these:

GITHUB_ACTOR=nektos/act
GITHUB_REPOSITORY=owner/repo
GITHUB_EVENT_NAME=push
GITHUB_SHA=abc123...
GITHUB_REF=refs/heads/main
ACT=true

Debugging

Verbose Output

bash
# Verbose mode
act -v

# Very verbose (debug)
act -vv

Step-by-Step Execution

bash
# Interactive mode - pause before each step
act --watch

Inspect Containers

bash
# Keep container running after workflow
act --reuse

# Then in another terminal
docker ps
docker exec -it <container-id> /bin/bash

Bind Mount Local Files

bash
# Mount current directory
act --bind

# Mount specific directory
act -b /host/path:/container/path

Common Workflows

Test Before Push

bash
# Validate workflow syntax
act --dryrun

# Run tests
act -j test

# Run full CI
act

Iterative Development

bash
# Edit workflow
vim .github/workflows/ci.yml

# Test immediately
act --reuse -j build

# Iterate quickly
act --reuse -j build

Matrix Testing

bash
# Run specific matrix combination
act --matrix os:ubuntu-latest --matrix node:20

# Run all combinations
act

Troubleshooting

Docker Issues

bash
# Check Docker is running
docker ps

# Pull required images manually
docker pull catthehacker/ubuntu:act-latest

# Clean up Docker resources
docker system prune -a

Permission Issues

bash
# Run with sudo (Linux)
sudo act

# Fix Docker permissions (Linux)
sudo usermod -aG docker $USER
newgrp docker

Missing Tools

bash
# Use fuller image
act -P ubuntu-latest=catthehacker/ubuntu:full-latest

# Or install in workflow
- run: |
    apt-get update
    apt-get install -y some-tool

Workflow Not Found

bash
# Check workflow files exist
ls -la .github/workflows/

# Validate YAML syntax
yamllint .github/workflows/*.yml

# List detected workflows
act -l

Action Compatibility

Some actions don't work with act:

yaml
# Skip action in act
- name: GitHub-only action
  if: ${{ !env.ACT }}
  uses: github/some-action@v1

# Use alternative in act
- name: Local alternative
  if: env.ACT == 'true'
  run: echo "Running local version"

Best Practices

DO

āœ… Use act --dryrun before running full workflows āœ… Create .actrc for consistent configuration āœ… Use .secrets file and add it to .gitignore āœ… Use --reuse for faster iteration āœ… Test workflows locally before pushing āœ… Use appropriate image sizes for your needs āœ… Document act usage in README

DON'T

āŒ Commit .secrets or .env files āŒ Use latest Docker tags in production āŒ Skip validation with --dryrun āŒ Run act without understanding what it will do āŒ Ignore Docker disk space usage āŒ Assume all actions work perfectly with act

Configuration Files

.actrc

# Platform mappings
-P ubuntu-latest=catthehacker/ubuntu:act-latest

# Default options
--reuse
--secret-file .secrets
--env-file .env

# Container options
--container-architecture linux/amd64

.github/workflows/.actrc

Project-specific overrides in workflows directory.

CI/CD Integration

Pre-Push Hook

.git/hooks/pre-push:

bash
#!/bin/bash
echo "Validating workflows..."
act --dryrun
if [ $? -ne 0 ]; then
  echo "Workflow validation failed"
  exit 1
fi

Make Target

makefile
.PHONY: test-workflows
test-workflows:
 act --dryrun
 act -j test

.PHONY: ci-local
ci-local:
 act --reuse

Performance Tips

Faster Iteration

bash
# Use reuse flag
act --reuse

# Skip checkout if not needed
act --reuse -j test --no-recurse

# Use smaller images for simple tests
act -P ubuntu-latest=node:20-alpine

Caching

Act respects GitHub Actions caching:

yaml
- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

Cache location on host: ~/.cache/act/

Related Skills

  • act-workflow-syntax: Creating and structuring workflow files
  • act-docker-setup: Configuring Docker for act
  • act-advanced-features: Advanced act usage patterns