metabuilder/docs/guides/getting-started/github-actions-local-testing.md

Testing GitHub Actions Locally with Act

This guide explains how to use act to run GitHub Actions workflows locally, helping diagnose and fix issues before pushing to GitHub.

What is Act?

Act allows you to run GitHub Actions workflows on your local machine using Docker. This enables rapid iteration and debugging without polluting your GitHub commit history with "fix CI" commits.

Installation

Linux

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

macOS

brew install act

Windows

choco install act-cli

Or download from: https://github.com/nektos/act/releases

Prerequisites

• Docker must be installed and running
• Sufficient disk space for runner images (~2-5GB)

Quick Start

1. List Available Workflows

act -l

This lists all jobs defined in .github/workflows/

2. Run All Jobs (Dry Run)

act -n

The -n flag performs a dry run without executing steps.

3. Run Specific Workflow

# Run push event workflows
act push

# Run pull request workflows
act pull_request

# Run a specific job
act -j lint
act -j build
act -j test-e2e

Our Project Workflows

CI/CD Workflow (ci.yml)

Tests linting, building, and e2e tests:

# Run entire CI pipeline
act push

# Run specific jobs
act -j prisma-check
act -j lint
act -j build
act -j test-e2e

Code Review Workflow (code-review.yml)

Automated PR review:

act pull_request -W .github/workflows/code-review.yml

Auto Merge Workflow (auto-merge.yml)

act workflow_run -W .github/workflows/auto-merge.yml

PR Management Workflow (pr-management.yml)

act pull_request -W .github/workflows/pr-management.yml

Common Issues and Solutions

Issue 1: Missing Secrets

Error:

Error: Required secret not found

Solution: Create a .secrets file in the project root:

GITHUB_TOKEN=your_github_token_here

Then run:

act --secret-file .secrets

Issue 2: Docker Image Size

Act downloads large Docker images. To use smaller images:

# Use medium-sized image (recommended)
act -P ubuntu-latest=catthehacker/ubuntu:act-latest

# Use smaller image (faster but may be missing some tools)
act -P ubuntu-latest=catthehacker/ubuntu:act-20.04

Issue 3: Insufficient Resources

Error:

Error: Process completed with exit code 137

Solution: Increase Docker's memory limit in Docker Desktop settings (recommend 8GB+).

Issue 4: Node/NPM Cache Issues

Some workflows use cache: 'npm' which may fail locally:

# Skip cache-related steps
act push --env ACT=true

Then modify workflows to skip cache when ACT env var is set.

Issue 5: Missing npm ci Dependencies

Error:

npm ERR! The `npm ci` command can only install with an existing package-lock.json

Solution: Ensure package-lock.json is committed and up-to-date:

npm install
git add package-lock.json
git commit -m "Update package-lock.json"

Workflow-Specific Testing

Testing Prisma Setup

act -j prisma-check

Expected issues to check:

• Missing prisma/schema.prisma
• Incorrect DATABASE_URL
• Missing Prisma dependencies

Testing Linting

act -j lint

This runs ESLint against the codebase. Fix errors before pushing.

Testing Build

act -j build

Simulates production build. Check for:

• TypeScript compilation errors
• Missing imports
• Build optimization issues

Testing E2E Tests

act -j test-e2e

Note: Playwright tests may not work perfectly in act due to browser dependencies. Consider:

• Running Playwright tests directly: npm run test:e2e
• Using GitHub Actions for full E2E validation

Advanced Usage

Run with Verbose Output

act -v

Run in Interactive Mode

act --bind

This allows you to inspect the container interactively.

Use Custom Event Payload

Create event.json:

{
  "pull_request": {
    "number": 1,
    "title": "Test PR",
    "body": "Testing locally"
  }
}

Run with:

act pull_request -e event.json

Set Environment Variables

act -e NODE_ENV=production -e DEBUG=true

Platform Specification

# Create .actrc file for consistent settings
cat > ~/.actrc << EOF
-P ubuntu-latest=catthehacker/ubuntu:act-latest
--secret-file .secrets
--env ACT=true
EOF

Debugging Workflows

Step 1: Identify the Failing Step

act -j <job-name> -v

Look for red error messages indicating which step failed.

Step 2: Check Logs

Act outputs detailed logs. Search for:

• Error:
• exit code 1
• Process completed with exit code

Step 3: Test Locally

If a command fails in act, test it directly:

# Example: If npm ci fails
npm ci

# Example: If lint fails
npm run lint

# Example: If build fails
npm run build

Step 4: Iterate

Make changes, then re-run:

act -j <job-name>

Current Known Issues in Our Workflows

CI/CD (ci.yml)

1. Prisma Dependencies Missing

   • Status: ❌ Failing
   • Issue: @prisma/client and prisma packages not installed
   • Fix: npm install @prisma/client prisma

2. Prisma Schema Missing

   • Status: ❌ Failing
   • Issue: No prisma/schema.prisma file
   • Fix: Create Prisma schema file

3. Test Script Missing

   • Status: ❌ Failing
   • Issue: test:e2e script not in package.json
   • Fix: Verify package.json has the script

Code Review (code-review.yml)

• Status: ⚠️ Requires PR context
• Can be tested with custom event payload

Auto Merge (auto-merge.yml)

• Status: ⚠️ Requires GitHub API access
• May not work fully in local environment

Best Practices

1. Run workflows before pushing:

   act -j lint && act -j build
   

2. Use specific job testing: Only run the jobs relevant to your changes.

3. Keep workflows simple: Complex workflows are harder to debug locally.

4. Mock external services: Use if: ${{ !env.ACT }} to skip steps that require GitHub-specific features.

5. Test incrementally: After fixing one job, test the next.

Continuous Integration Best Practices

Before Every Push

# Quick validation
npm run lint
npm run build
npm run test:e2e

# Or use act to validate workflows
act push -j lint -j build

Before Creating PR

# Full CI simulation
act push

# Simulate PR checks
act pull_request

Troubleshooting Checklist

• Docker is running
• Act is installed (act --version)
• .secrets file exists (if secrets needed)
• package-lock.json is committed
• All dependencies are installed (npm install)
• Prisma schema exists (if using Prisma)
• Scripts in package.json match workflow expectations

Additional Resources

• Act Documentation
• GitHub Actions Documentation
• Act Variables and Secrets
• Workflow Syntax

Getting Help

If workflows still fail after testing with act:

1. Check the project issues
2. Review recent commits for workflow changes
3. Compare with working workflows in other projects
4. Test commands individually outside of workflows

Quick Reference

# List all workflows
act -l

# Dry run
act -n

# Run push workflows
act push

# Run PR workflows
act pull_request

# Run specific job
act -j <job-name>

# Verbose output
act -v

# With secrets
act --secret-file .secrets

# Custom platform
act -P ubuntu-latest=catthehacker/ubuntu:act-latest