A lightweight CLI tool for running GitHub Actions workflows locally

Raptor is a CLI tool for running GitHub Actions workflow files (.github/workflows/*.yml) in your local environment. Test your CI pipelines locally before pushing.

• Native support for GitHub Actions workflow YAML
• Job dependencies (needs) with automatic dependency resolution
• Environment variables support at workflow/job/step levels
• Dynamic environment variable propagation via GITHUB_ENV / GITHUB_PATH
• Per-step working directory configuration
• Lightweight and simple design

Download the binary for your platform from the releases page.

curl -LO https://github.com/watany-dev/raptor/releases/download/v0.2.0/raptor_0.2.0_Linux_x86_64.tar.gz
tar xzf raptor_0.2.0_Linux_x86_64.tar.gz
sudo mv raptor /usr/local/bin/
raptor --version

curl -LO https://github.com/watany-dev/raptor/releases/download/v0.2.0/raptor_0.2.0_Linux_arm64.tar.gz
tar xzf raptor_0.2.0_Linux_arm64.tar.gz
sudo mv raptor /usr/local/bin/
raptor --version

curl -LO https://github.com/watany-dev/raptor/releases/download/v0.2.0/raptor_0.2.0_Darwin_arm64.tar.gz
tar xzf raptor_0.2.0_Darwin_arm64.tar.gz
sudo mv raptor /usr/local/bin/
raptor --version

curl -LO https://github.com/watany-dev/raptor/releases/download/v0.2.0/raptor_0.2.0_Darwin_x86_64.tar.gz
tar xzf raptor_0.2.0_Darwin_x86_64.tar.gz
sudo mv raptor /usr/local/bin/
raptor --version

go install github.com/watany-dev/raptor/cmd/raptor@v0.2.0

git clone https://github.com/watany-dev/raptor.git
cd raptor
go build -o raptor ./cmd/raptor
sudo mv raptor /usr/local/bin/

• Supported platforms: Linux, macOS (Windows is not supported)
• Runtime: Git 2.5 or later
• Build from source only: Go 1.24 or later

# Run a specific job
raptor run --workflow <workflow-file> --job <job-id>

# Run all jobs (omit --job)
raptor run --workflow <workflow-file>

Note: All workflows are executed in isolated Git worktrees for security.

Dry-run mode allows you to preview what will be executed without actually running the workflow. Useful for checking and debugging CI pipelines.

# Explicitly specify dry-run flag
raptor run -w ci.yml --dry-run
raptor run -w ci.yml -n

# Omit run subcommand for automatic dry-run mode
raptor -w ci.yml

Example dry-run output:

🔍 DRY RUN MODE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Workflow: .github/workflows/ci.yml
Name: CI
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 Job: build
   Runs-on: ubuntu-latest

   [1] Build
       Command:
         echo "Building..."

📋 Job: test
   Depends on: build
   Runs-on: ubuntu-latest

   [1] Test
       Command:
         echo "Testing..."

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
To execute this workflow, use: raptor run -w .github/workflows/ci.yml

Information displayed:

• Workflow name and path
• Job ID, name, and runs-on
• Each step's name, working directory, conditions (if), number of environment variables, and command content

# Run the build job from CI workflow
raptor run --workflow .github/workflows/ci.yml --job build

# Use short form
raptor run -w ci.yml -j test

# Run all jobs in workflow
raptor run -w ci.yml

# Run with specified working directory
raptor run -w .github/workflows/ci.yml -j lint -C /path/to/project

When using -j to run a specific job, Raptor automatically resolves and executes all its dependencies first:

# If deploy needs test, and test needs build:
# This runs: build → test → deploy
raptor run -w ci.yml -j deploy

If a dependency fails, dependent jobs are automatically skipped:

INFO running job job_id=build
INFO running job job_id=test
INFO skipping job job_id=deploy reason="dependency 'test' failed"

raptor help
raptor --help

raptor version
raptor --version
raptor -v

Currently supported GitHub Actions syntax:

Conditional step execution is supported:

steps:
  - name: Always run
    if: true
    run: echo "This always runs"

  - name: Conditional
    if: ${{ env.MY_VAR == 'value' }}
    run: echo "Runs when MY_VAR is 'value'"

  - name: On failure
    if: failure()
    run: echo "Runs only if previous step failed"

  - name: Always (even on failure)
    if: always()
    run: echo "Cleanup step"

  - name: Complex conditions with AND/OR
    if: ${{ success() && env.DEPLOY_ENV == 'production' }}
    run: echo "Deploy to production"

  - name: String functions
    if: ${{ startsWith(env.BRANCH_NAME, 'feature/') }}
    run: echo "Feature branch detected"

  - name: File hash for caching
    if: ${{ hashFiles('package.json') != '' }}
    run: echo "package.json exists"

Supported conditional syntax:

Error Handling:

By default, Raptor uses strict mode for condition evaluation. If a condition has syntax errors or evaluation errors, the workflow will stop with a clear error message. This helps catch typos and invalid expressions early.

# Default behavior: strict mode
raptor run -w workflow.yml
# Error: failed to evaluate if condition: condition parse error: unexpected token

# Legacy behavior: ignore errors and continue
raptor run -w workflow.yml --ignore-if-errors
# Warning: failed to evaluate if condition: parse error: ... (defaulting to true)

Example workflow that can be run with Raptor:

name: CI

env:
  GLOBAL_VAR: "global-value"

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Build
        run: echo "Building..."

  test:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Test
        run: echo "Testing..."

  deploy:
    runs-on: ubuntu-latest
    needs: [build, test]
    steps:
      - name: Deploy
        if: success()
        run: echo "Deploying..."

Since Raptor executes commands described in workflow files, only run trusted workflows.

• Isolated execution: All workflows run in isolated Git worktrees
• Absolute path prohibition: Absolute paths cannot be used in working-directory
• Environment variable protection: Dangerous environment variables like LD_PRELOAD are blocked
• Input validation: Environment variable names and values are validated

See SECURITY.md for details.

Raptor runs workflows with your user permissions. Malicious workflows can:

• Delete or modify files
• Access network
• Send data externally

Always verify the content before running.

go build ./...

go test ./...

go test -cover ./...

raptor/
├── cmd/raptor/        # CLI entry point
├── internal/
│   ├── cli/           # CLI flag parsing and runner
│   ├── dag/           # Job dependency graph (topological sort)
│   ├── envfiles/      # GITHUB_ENV/GITHUB_PATH parsing
│   ├── executor/      # Command execution engine
│   ├── expression/    # Expression evaluation (if conditions)
│   ├── runtime/       # Environment variable merging
│   ├── security/      # Security validation
│   ├── util/          # Git operation utilities
│   ├── workflow/      # Workflow YAML parsing
│   └── worktree/      # Git worktree management
└── docs/              # Development documentation

Apache License 2.0