Essential GitHub Actions Runner

Run GitHub Actions workflows locally with the same fidelity as GitHub's servers. Completely offline, zero configuration, minimal complexity.

Quick Start

./ci                              # Run .github/workflows/ci.yml
./ci .github/workflows/test.yml   # Run specific workflow

That's it. No installation, no setup, no configuration files.

What It Does

1. Reads your GitHub Actions workflow file
2. Extracts all - run: commands from the workflow
3. Executes them in Ubuntu Jammy (same as GitHub's ubuntu-latest)
4. Sets the same environment variables GitHub Actions uses
5. Mounts your project at /github/workspace (GitHub's exact path)
6. Cleans up automatically - no artifacts left behind

Example

Your workflow .github/workflows/ci.yml:

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test
      - run: npm run build

Run locally:

./ci

Executes: npm ci; npm test; npm run build in the same Ubuntu environment GitHub uses.

Why This Approach

High Fidelity

• Same Ubuntu version - Uses ubuntu:jammy (GitHub's current ubuntu-latest)
• Same paths - Your code lives at /github/workspace
• Same environment - CI=true, GITHUB_ACTIONS=true, etc.
• Same package versions - Fresh Ubuntu container each time

Essential Complexity Only

• 12 lines of bash - No VMs, no act installation, no configuration
• Uses Docker - Leverages existing container technology
• Offline capable - Works without internet after initial image pull
• No cleanup needed - Container is removed automatically

Focused Scope

• Runs - run: commands - The core of most CI workflows
• Ignores complex actions - Focuses on the 80% use case
• Stable base - Won't break when GitHub changes ubuntu-latest

What It Doesn't Do

This tool focuses on the essential complexity. It doesn't:

• Handle uses: actions (checkout, setup-node, etc.)
• Support multiple jobs or complex workflows
• Provide perfect GitHub compatibility
• Install additional tools beyond basic Ubuntu packages

For these cases, your workflow should be robust enough to install what it needs, or use tools like act for full GitHub Actions compatibility.

Use Cases

✅ Perfect For

• Node.js projects - npm ci && npm test && npm run build
• Python projects - pip install -r requirements.txt && pytest
• Go projects - go mod download && go test ./...
• Static sites - Jekyll, Hugo, simple build processes
• Quick validation - Test workflow changes before pushing

❌ Not Ideal For

• Complex multi-job workflows
• Workflows heavily dependent on GitHub-specific actions
• Matrix builds across multiple environments
• Workflows requiring specific GitHub context/secrets

Examples

Node.js Project

# .github/workflows/ci.yml
name: CI
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
      - run: apt-get install -y nodejs
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run build

Python Project

# .github/workflows/ci.yml
name: CI
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: apt-get update && apt-get install -y python3-pip
      - run: pip install -r requirements.txt
      - run: python -m pytest
      - run: python -m flake8 .

GitHub Pages Site

# .github/workflows/pages.yml
name: Build and Deploy
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: apt-get update && apt-get install -y ruby-full build-essential zlib1g-dev
      - run: gem install jekyll bundler
      - run: bundle install
      - run: bundle exec jekyll build

Troubleshooting

Workflow file not found

./ci .github/workflows/your-workflow.yml

Missing dependencies

Add installation commands to your workflow:

- run: apt-get update && apt-get install -y your-package

Permission errors

The container runs as root, so file permissions should work automatically.

Slow first run

Docker needs to pull the Ubuntu image (~200MB). Subsequent runs are fast.

Philosophy: Essential vs Accidental Complexity

This tool embodies Dijkstra's concept of focusing on essential complexity:

• Essential: Run CI commands in isolated, reproducible environment
• Accidental: Perfect GitHub compatibility, complex workflow parsing, VM management

By focusing only on what's essential, we get:

• Simplicity: 12 lines vs 500+ in other solutions
• Reliability: Fewer moving parts, fewer failure modes
• Maintainability: Easy to understand and modify
• Longevity: Won't break when GitHub changes their infrastructure

The result catches 80% of CI issues with 5% of the complexity.