GitLab CI/CD Local Tester

Release Notice: This is a beta version (1.0.0-beta.1) of the tool. While it's feature-complete and usable in production, you may encounter some issues. Please report any bugs or suggestions in our issue tracker.

A comprehensive tool for testing GitLab CI/CD pipelines locally with both Web UI and Terminal CLI interfaces. Similar to GitHub's act tool but designed specifically for GitLab CI/CD.

🚀 Features

Web Interface

• 🔍 Project Scanner: Automatically scan project directories for GitLab CI/CD configurations
• 📝 YAML Editor: Advanced Monaco-based editor with syntax highlighting and validation
• 🎯 Pipeline Visualization: Visual representation of your CI/CD pipeline stages and jobs
• 🚀 Execution Simulation: Real-time pipeline execution simulation with detailed logs
• 📦 Nixpacks Support: Automatic detection and integration of nixpacks.toml configurations
• 🐳 Docker Integration: Support for Dockerfile-based builds
• 📱 Responsive Design: Beautiful, modern UI that works on all devices

Terminal CLI

• ⚡ Fast Execution: Run pipelines directly from terminal
• 🔍 Project Scanning: Detect GitLab CI configurations automatically
• 📋 Pipeline Validation: Validate YAML syntax and configuration
• 🎯 Selective Execution: Run specific jobs or stages
• 📊 Detailed Reporting: Comprehensive execution summaries
• 🛠️ Template Generation: Initialize projects with pre-built templates

📦 Installation

Option 1: NPM Global Install

npm install -g dryrun-ci

Option 2: Clone and Build

git clone https://github.com/Asimatic-Labs/dryrun.git
cd dryrun
npm install
npm run build-cli
npm link

Option 3: Download Binary

Download pre-built binaries from the releases page.

🖥️ CLI Usage

Quick Start

# Scan current project
dryrun-ci scan

# Initialize GitLab CI configuration
dryrun-ci init

# Run pipeline
dryrun-ci run

# Start web interface
dryrun-ci web

Available Commands

scan - Project Analysis

# Scan current directory
dryrun-ci scan

# Scan specific path
dryrun-ci scan --path /path/to/project

run - Execute Pipeline

# Run full pipeline
dryrun-ci run

# Run specific job
dryrun-ci run --job build_job

# Run specific stage
dryrun-ci run --stage test

# Dry run (show execution plan)
dryrun-ci run --dry-run

# Use custom CI file
dryrun-ci run --file custom-ci.yml

init - Initialize Configuration

# Create basic configuration
dryrun-ci init

# Use specific template
dryrun-ci init --template docker
dryrun-ci init --template nixpacks

web - Web Interface

# Start on default port (3000)
dryrun-ci web

# Start on custom port
dryrun-ci web --port 8080

Short Alias

Use gct as a shorter alias:

gct scan
gct run
gct init --template docker

🌐 Web Interface Usage

Getting Started

1. Start the web interface:

   npm run dev
   # or
   dryrun-ci web

2. Open http://localhost:3000 in your browser

3. Choose your workflow:

   • Project Scanner: Load existing project with GitLab CI
   • YAML Editor: Create or edit pipeline configuration
   • Pipeline View: Visualize and run your pipeline

Project Scanning

• Click "Select Project Directory" to scan your project
• The scanner automatically detects:
  • .gitlab-ci.yml files
  • nixpacks.toml configuration
  • package.json files
  • Dockerfiles

YAML Configuration

• Use the built-in editor to create or modify your GitLab CI/CD configuration
• Real-time validation ensures your YAML is correct
• Load example templates or generate from nixpacks.toml

Pipeline Visualization

• View your pipeline stages and jobs in a visual format
• See job dependencies and execution flow
• Monitor job status and duration

Execution Testing

• Run your pipeline locally to test configuration
• View real-time logs and output
• Debug failed jobs with detailed error information

📋 Supported File Types

• GitLab CI/CD: .gitlab-ci.yml, .gitlab-ci.yaml
• Nixpacks: nixpacks.toml
• Docker: Dockerfile, dockerfile
• Node.js: package.json

🔧 Configuration Examples

Basic Pipeline

stages:
  - build
  - test
  - deploy

build_job:
  stage: build
  image: node:18
  script:
    - npm install
    - npm run build
  artifacts:
    paths:
      - dist/

test_job:
  stage: test
  image: node:18
  script:
    - npm test
  dependencies:
    - build_job

deploy_job:
  stage: deploy
  script:
    - echo "Deploying application"
  when: manual

Docker Pipeline

stages:
  - build
  - test
  - deploy

build_image:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker build -t myapp .

test_app:
  stage: test
  image: myapp:latest
  script:
    - npm test

deploy_production:
  stage: deploy
  image: docker:latest
  script:
    - docker push myapp:latest
  only:
    - main

Nixpacks Pipeline

stages:
  - build
  - test
  - deploy

variables:
  NIXPACKS_BUILD: "true"

build_with_nixpacks:
  stage: build
  image: nixos/nix
  script:
    - nixpacks build . --name myapp
  artifacts:
    paths:
      - dist/

test_app:
  stage: test
  script:
    - npm test
  dependencies:
    - build_with_nixpacks

🚀 Advanced Features

Environment Variables

Set custom variables for your pipeline:

variables:
  NODE_ENV: "production"
  API_URL: "https://api.example.com"

Job Dependencies

Control job execution order:

deploy_job:
  dependencies:
    - build_job
    - test_job

Conditional Execution

Run jobs based on conditions:

deploy_job:
  only:
    - main
  when: manual

Artifacts

Share files between jobs:

build_job:
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour

🛠️ Development

Prerequisites

• Node.js 18 or higher
• Modern web browser (Chrome, Firefox, Safari, Edge)

Setup

git clone https://github.com/your-username/gitlab-ci-local-tester.git
cd gitlab-ci-local-tester
npm install

Development Commands

# Start web development server
npm run dev

# Build CLI
npm run build-cli

# Run CLI locally
npm run cli

# Build for production
npm run build

# Create binary packages
npm run pkg

Project Structure

├── src/
│   ├── app/                 # Next.js web interface
│   ├── components/          # React components
│   ├── utils/              # Shared utilities
│   ├── types/              # TypeScript types
│   └── store/              # State management
├── bin/
│   └── cli.js              # CLI entry point
├── package.json
└── README.md

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details

🆘 Support

For issues and questions:

• Create an issue on GitHub
• Check the documentation
• Review example configurations

🔗 Related Tools

• act - Run GitHub Actions locally
• GitLab Runner - Official GitLab CI/CD runner
• Nixpacks - App source + Nix packages + Docker

🔗 Links

• NPM Package: npmjs.com/package/dryrun-ci
• Documentation: docs/
• Issues: GitHub Issues

Built with ❤️ for the GitLab community

Whether you prefer a beautiful web interface or the speed of terminal commands, GitLab CI/CD Local Tester has you covered. Test your pipelines locally, catch errors early, and deploy with confidence!