FORGE - Local CI/CD Runner

Fast, Offline, Reliable, Go-anywhere Execution

About FORGE

FORGE is a lightweight local CI/CD tool built with Rust that allows you to run automation pipelines on your local machine. It's extremely useful for developing and testing pipelines before pushing them to larger CI/CD systems.

Why FORGE?

• Local & Fast: Run pipelines on your local machine without waiting for CI/CD servers
• Offline-First: Works without an internet connection (as long as Docker images are available locally)
• Compatible: Syntax similar to GitHub Actions and GitLab CI
• Lightweight: Minimal resource consumption
• Portable: Runs on Windows, macOS, and Linux

Features

• Run CI/CD pipelines from simple YAML files
• Isolation using Docker containers
• Support for various Docker images
• Real-time log streaming with colors (parallel stages buffer logs and print in definition order)
• Environment variables management
• Intuitive command-line interface
• Multi-stage pipelines with parallel execution
• Caching to speed up builds (repo-local cache in ./.forge/cache/)
• Secure secrets management (secrets are masked in verbose env output; commands can still echo secrets)
• Dependencies between stages

Quick Start

Installation

# With Cargo
cargo install forge

# Or download a pre-compiled binary from the latest GitHub Release
# Linux (amd64)
curl -L https://github.com/0xReLogic/Forge/releases/latest/download/forge-linux-amd64 -o forge

# Linux (arm64)
curl -L https://github.com/0xReLogic/Forge/releases/latest/download/forge-linux-arm64 -o forge

chmod +x forge
./forge --version
# Optional (install to PATH): sudo install -m 755 forge /usr/local/bin/forge

# macOS (Intel)
curl -L https://github.com/0xReLogic/Forge/releases/latest/download/forge-macos-amd64 -o forge

# macOS (Apple Silicon)
curl -L https://github.com/0xReLogic/Forge/releases/latest/download/forge-macos-arm64 -o forge

chmod +x forge
./forge --version
# Optional (install to PATH): sudo install -m 755 forge /usr/local/bin/forge

Windows (PowerShell):

Invoke-WebRequest -Uri https://github.com/0xReLogic/Forge/releases/latest/download/forge-windows-amd64.exe -OutFile forge.exe
.\forge.exe --version
# Optional: move forge.exe into a directory on PATH (or add its directory to PATH)

# Or from source
git clone https://github.com/0xReLogic/Forge.git
cd Forge
cargo build --release

Prerequisites: Rust (1.91+) and Docker (20.10+; tested on 28.2.2)

For detailed installation instructions, see docs/installation.md.

Usage

# Initialize a project
forge init

# Validate configuration
forge validate

# Run the pipeline
forge run

Secrets via .env (Recommended)

FORGE reads secret values from environment variables. To avoid exporting secrets manually every time, you can store them in a local .env file.

cp .env.example .env
# edit .env and set values like FORGE_API_TOKEN=...

forge run

FORGE automatically loads .env from:

• Current working directory
• The config file directory (when using --file path/to/forge.yaml)

For more commands and options, see docs/usage.md.

Documentation

• Installation Guide - Detailed installation instructions for all platforms
• Usage Guide - Complete command reference and workflows
• Configuration Reference - YAML format and all configuration options
• Examples - Real-world examples for different tech stacks
• Architecture - System design and component details

Quick Example

version: "1.0"
stages:
  - name: build
    steps:
      - name: Install Dependencies
        command: npm install
        image: node:16-alpine
        working_dir: /workspace
  - name: test
    steps:
      - name: Run Tests
        command: npm test
        image: node:16-alpine
        working_dir: /workspace
    depends_on:
      - build
cache:
  enabled: true
  directories:
    - /workspace/node_modules

Validate and preview what will run:

forge validate --file forge.yaml
forge run --file forge.yaml --dry-run --verbose

Cache storage:

• Cache data is stored inside your project at ./.forge/cache/.
• FORGE derives a cache key from common lockfiles (e.g. Cargo.lock, package-lock.json, pnpm-lock.yaml, yarn.lock, go.sum), so different dependency states use different cache folders.
• To reset cache for a project, delete the .forge/ directory.

Parallel Execution

Run independent tasks simultaneously for faster pipelines:

version: "1.0"
stages:
  - name: test
    parallel: true
    steps:
      - name: Unit Tests
        command: npm run test:unit
        image: node:18-alpine

      - name: Integration Tests
        command: npm run test:integration
        image: node:18-alpine

      - name: Lint
        command: npm run lint
        image: node:18-alpine

All three steps run concurrently instead of sequentially (3× faster).

Stage Dependencies

Define complex pipelines with stage dependencies:

stages:
  - name: setup
    steps: [...]
  
  - name: build
    depends_on: [setup]
    steps: [...]
  
  - name: test
    depends_on: [build]
    steps: [...]
  
  - name: deploy
    depends_on: [build, test]
    steps: [...]

FORGE automatically resolves execution order and detects circular dependencies.

More examples in docs/examples.md and examples/ directory.

Contributing

Thank you for your great contributions!

Good First Issues: Check out our good first issue label for beginner-friendly tasks.

How to Contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Read CONTRIBUTING.md for detailed guidelines.

License

This project is licensed under the MIT License.

Credits

Inspired by GitHub Actions, GitLab CI, and Jenkins.