GitLab CI/CD Local Tester

Beta 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

1npm install -g dryrun-ci

Option 2: Clone and Build

1git clone https://github.com/Asimatic-Labs/dryrun.git
2cd dryrun
3npm install
4npm run build-cli
5npm link

Option 3: Download Binary

Download pre-built binaries from the releases page.

🖥️ CLI Usage

Quick Start

1# Scan current project
2dryrun-ci scan
3
4# Initialize GitLab CI configuration
5dryrun-ci init
6
7# Run pipeline
8dryrun-ci run
9
10# Start web interface
11dryrun-ci web

Available Commands

scan - Project Analysis

1# Scan current directory
2dryrun-ci scan
3
4# Scan specific path
5dryrun-ci scan --path /path/to/project

run - Execute Pipeline

1# Run full pipeline
2dryrun-ci run
3
4# Run specific job
5dryrun-ci run --job build_job
6
7# Run specific stage
8dryrun-ci run --stage test
9
10# Dry run (show execution plan)
11dryrun-ci run --dry-run
12
13# Use custom CI file
14dryrun-ci run --file custom-ci.yml

init - Initialize Configuration

1# Create basic configuration
2dryrun-ci init
3
4# Use specific template
5dryrun-ci init --template docker
6dryrun-ci init --template nixpacks

web - Web Interface

1# Start on default port (3000)
2dryrun-ci web
3
4# Start on custom port
5dryrun-ci web --port 8080

Short Alias

Use gct as a shorter alias:

1gct scan
2gct run
3gct init --template docker

🌐 Web Interface Usage

Getting Started

1. Start the web interface:

   1npm run dev
   2# or
   3dryrun-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

1stages:
2  - build
3  - test
4  - deploy
5
6build_job:
7  stage: build
8  image: node:18
9  script:
10    - npm install
11    - npm run build
12  artifacts:
13    paths:
14      - dist/
15
16test_job:
17  stage: test
18  image: node:18
19  script:
20    - npm test
21  dependencies:
22    - build_job
23
24deploy_job:
25  stage: deploy
26  script:
27    - echo "Deploying application"
28  when: manual

Docker Pipeline

1stages:
2  - build
3  - test
4  - deploy
5
6build_image:
7  stage: build
8  image: docker:latest
9  services:
10    - docker:dind
11  script:
12    - docker build -t myapp .
13
14test_app:
15  stage: test
16  image: myapp:latest
17  script:
18    - npm test
19
20deploy_production:
21  stage: deploy
22  image: docker:latest
23  script:
24    - docker push myapp:latest
25  only:
26    - main

Nixpacks Pipeline

1stages:
2  - build
3  - test
4  - deploy
5
6variables:
7  NIXPACKS_BUILD: "true"
8
9build_with_nixpacks:
10  stage: build
11  image: nixos/nix
12  script:
13    - nixpacks build . --name myapp
14  artifacts:
15    paths:
16      - dist/
17
18test_app:
19  stage: test
20  script:
21    - npm test
22  dependencies:
23    - build_with_nixpacks

🚀 Advanced Features

Environment Variables

Set custom variables for your pipeline:

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

Job Dependencies

Control job execution order:

1deploy_job:
2  dependencies:
3    - build_job
4    - test_job

Conditional Execution

Run jobs based on conditions:

1deploy_job:
2  only:
3    - main
4  when: manual

Artifacts

Share files between jobs:

1build_job:
2  artifacts:
3    paths:
4      - dist/
5    expire_in: 1 hour

🛠️ Development

Prerequisites

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

Setup

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

Development Commands

1# Start web development server
2npm run dev
3
4# Build CLI
5npm run build-cli
6
7# Run CLI locally
8npm run cli
9
10# Build for production
11npm run build
12
13# Create binary packages
14npm 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!