GitHub Actions Local Testing with Act CLI

Complete guide to running GitHub Actions workflows locally on Linux using Act CLI for faster development and testing

Difficulty: 🟡 Intermediate
Estimated Time: 20-30 minutes
Prerequisites: Basic GitHub Actions knowledge, Linux command line experience, Docker installed, Understanding of CI/CD concepts

What You'll Learn

This tutorial covers essential GitHub Actions local testing concepts and tools:

Act CLI Setup - Installing and configuring Act CLI on Linux
Local Workflow Execution - Running GitHub Actions workflows without pushing to GitHub
Docker Integration - Using Docker containers for workflow execution
Debugging and Testing - Troubleshooting workflows locally before deployment
Best Practices - Efficient local development workflow strategies

Prerequisites

Basic GitHub Actions knowledge
Linux command line experience
Docker installed and running
Understanding of CI/CD concepts

Main Tutorials Hub - Step-by-step implementation guides
DevOps Tutorials - Infrastructure automation and deployment guides
Docker Tutorials - Container and orchestration guides

Introduction

GitHub Actions is a powerful CI/CD platform, but waiting for every workflow run to complete on GitHub can slow down development. Act CLI allows you to run GitHub Actions workflows locally on your Linux machine, dramatically speeding up the development and testing cycle.

Why Use Act CLI?

Faster Development - Test workflows instantly without pushing to GitHub
Offline Development - Work on workflows without internet dependency
Cost Savings - Avoid consuming GitHub Actions minutes during development
Better Debugging - Detailed local execution logs and error messages
Team Collaboration - Share workflow configurations before GitHub deployment

Step-by-Step Instructions

Step 1: Install Act CLI

Using Package Manager (Recommended)

# Install using snap (Ubuntu/Debian)
sudo snap install act

# Or using Homebrew (if available)
brew install act

# Verify installation
act --version

Manual Installation

# Download latest release
curl -s https://api.github.com/repos/nektos/act/releases/latest | grep "browser_download_url.*Linux_x86_64.tar.gz" | cut -d : -f 2,3 | tr -d \" | wget -qi -

# Extract and install
tar -xzf act_Linux_x86_64.tar.gz
sudo mv act /usr/local/bin/
rm act_Linux_x86_64.tar.gz

# Verify installation
act --version

Step 2: Verify Docker Installation

Act CLI requires Docker to run workflows:

# Check Docker status
docker --version
docker ps

# Ensure Docker daemon is running
sudo systemctl status docker

Step 3: Create a Test Workflow

Create a simple GitHub Actions workflow for testing:

mkdir act-test-project
cd act-test-project

# Create workflows directory
mkdir -p .github/workflows

# Create a simple workflow
cat > .github/workflows/test.yml << 'EOF'
name: Test Workflow

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '18'
        
    - name: Install dependencies
      run: |
        echo "Installing dependencies..."
        npm install
        
    - name: Run tests
      run: |
        echo "Running tests..."
        npm test
        
    - name: Build project
      run: |
        echo "Building project..."
        npm run build
EOF

Step 4: Run Your First Workflow

Execute the workflow locally:

# Run the workflow
act

# Run with verbose output
act -v

# Run a specific job
act -j test

# Run with specific event
act push

Step 5: Create a Simple Node.js Project

For a complete test, create a basic Node.js project:

# Initialize Node.js project
npm init -y

# Install basic dependencies
npm install --save-dev jest

# Create package.json scripts
cat > package.json << 'EOF'
{
  "name": "act-test-project",
  "version": "1.0.0",
  "description": "Test project for Act CLI",
  "main": "index.js",
  "scripts": {
    "test": "jest",
    "build": "echo 'Building project...'",
    "start": "node index.js"
  },
  "devDependencies": {
    "jest": "^29.0.0"
  }
}
EOF

# Create a simple test file
mkdir test
cat > test/sample.test.js << 'EOF'
describe('Sample Test', () => {
  test('should pass', () => {
    expect(1 + 1).toBe(2);
  });
});
EOF

# Create a simple index file
cat > index.js << 'EOF'
console.log('Hello from Act CLI test project!');
EOF

Advanced Configuration

Custom Act Configuration

Create an .actrc file for persistent configuration:

# Create configuration file
cat > .actrc << 'EOF'
--platform ubuntu-latest=nektos/act-environments-ubuntu:18.04
--platform ubuntu-20.04=nektos/act-environments-ubuntu:20.04
--platform ubuntu-22.04=nektos/act-environments-ubuntu:22.04
--platform windows-latest=nektos/act-environments-windows:2019
--platform macos-latest=nektos/act-environments-macos:12
--reuse
--bind
--artifact-server-path /tmp/artifacts
EOF

Environment Variables

Set environment variables for your workflows:

# Create environment file
cat > .env << 'EOF'
NODE_ENV=development
DATABASE_URL=postgresql://localhost/testdb
API_KEY=test-key-123
EOF

# Run with environment file
act --env-file .env

Secrets Management

Handle secrets in local development:

# Create secrets file
cat > .secrets << 'EOF'
GITHUB_TOKEN=ghp_your_token_here
DATABASE_PASSWORD=local_password
AWS_ACCESS_KEY_ID=test_key
AWS_SECRET_ACCESS_KEY=test_secret
EOF

# Run with secrets
act --secret-file .secrets

Workflow Examples

Python Workflow

# .github/workflows/python-test.yml
name: Python Tests

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      
    - name: Setup Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.11'
        
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -r requirements.txt
        
    - name: Run tests
      run: |
        python -m pytest
        
    - name: Run linting
      run: |
        python -m flake8

Docker Workflow

# .github/workflows/docker-build.yml
name: Docker Build

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      
    - name: Build Docker image
      run: |
        docker build -t myapp:latest .
        
    - name: Run tests in container
      run: |
        docker run --rm myapp:latest npm test

Troubleshooting Common Issues

Docker Permission Issues

# Add user to docker group
sudo usermod -aG docker $USER

# Log out and back in, or restart session
newgrp docker

# Verify permissions
docker ps

Workflow Execution Problems

# Check workflow syntax
act --list

# Run with debug output
act -v --debug

# Check Docker images
docker images | grep act

# Clean up Docker resources
docker system prune -f

Platform Compatibility Issues

# Use specific platform
act --platform ubuntu-latest=nektos/act-environments-ubuntu:22.04

# Pull latest images
docker pull nektos/act-environments-ubuntu:22.04

# Check available platforms
act --list-platforms

Best Practices

1. Workflow Development

Start Simple - Begin with basic workflows and add complexity gradually
Test Locally First - Always test workflows with Act CLI before pushing to GitHub
Use Reusable Actions - Leverage existing actions from the GitHub Marketplace
Version Actions - Pin action versions for reproducible builds

2. Performance Optimization

Use Caching - Implement caching for dependencies and build artifacts
Parallel Jobs - Run independent jobs in parallel when possible
Conditional Steps - Use conditional execution to skip unnecessary steps
Resource Limits - Set appropriate resource limits for your workflows

3. Security Considerations

Secrets Management - Never hardcode secrets in workflow files
Action Security - Use actions from trusted sources and verify checksums
Permission Scoping - Use minimal required permissions for workflows
Dependency Scanning - Regularly scan for vulnerable dependencies

4. Local Development Workflow

# 1. Create or modify workflow
nano .github/workflows/my-workflow.yml

# 2. Test locally
act -W .github/workflows/my-workflow.yml

# 3. Debug issues
act -v --debug

# 4. Test with different events
act push
act pull_request
act workflow_dispatch

# 5. Commit and push when satisfied
git add .github/workflows/
git commit -m "Add new workflow"
git push

Integration with Development Tools

VS Code Integration

Install the "GitHub Actions" extension for VS Code:

# Install extension
code --install-extension github.vscode-github-actions

# Features:
# - Workflow syntax highlighting
# - IntelliSense for actions
# - Workflow validation
# - Integration with Act CLI

Pre-commit Hooks

Add workflow validation to your pre-commit hooks:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/nektos/act
    rev: v0.2.0
    hooks:
      - id: act-validate
        args: [--list]

CI/CD Pipeline Integration

Use Act CLI in your existing CI/CD pipeline:

# .github/workflows/validate-workflows.yml
name: Validate Workflows

on:
  pull_request:
    paths:
      - '.github/workflows/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      
    - name: Install Act CLI
      run: |
        curl -s https://api.github.com/repos/nektos/act/releases/latest | \
        grep "browser_download_url.*Linux_x86_64.tar.gz" | \
        cut -d : -f 2,3 | tr -d \" | wget -qi -
        tar -xzf act_Linux_x86_64.tar.gz
        sudo mv act /usr/local/bin/
        
    - name: Validate workflows
      run: |
        act --list
        act --dryrun

Conclusion

Act CLI transforms GitHub Actions development by enabling local testing and debugging. This powerful tool significantly reduces development time and improves workflow quality.

Key Takeaways

Local Development - Test workflows instantly without GitHub commits
Faster Iteration - Rapid development and debugging cycles
Cost Efficiency - Save GitHub Actions minutes during development
Better Quality - Catch issues early in the development process

Next Steps

Install Act CLI on your development machine
Create Test Workflows to familiarize yourself with the tool
Integrate with Your Workflow - Add Act CLI to your development process
Explore Advanced Features - Custom platforms, secrets management, and more

Start using Act CLI today and experience the difference in your GitHub Actions development workflow!

Tags: #GitHubActions #ActCLI #CICD #LocalTesting #WorkflowDevelopment #DevOps #Automation

CI/CD

Kubernetes