dryrun-ci/README.md

DryRun CI - Local GitLab CI/CD pipeline testing tool with Docker execution, performance monitoring, and security sandboxing

# 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](https://github.com/Asimatic-Labs/dryrun/issues).

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
```bash
npm install -g dryrun-ci
```

### Option 2: Clone and Build
```bash
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](https://github.com/Asimatic-Labs/dryrun/releases).

## 🖥️ CLI Usage

### Quick Start
```bash
# 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
```bash
# Scan current directory
dryrun-ci scan

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

#### `run` - Execute Pipeline
```bash
# 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
```bash
# Create basic configuration
dryrun-ci init

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

#### `web` - Web Interface
```bash
# 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:
```bash
gct scan
gct run
gct init --template docker
```

## 🌐 Web Interface Usage

### Getting Started

1. **Start the web interface:**
   ```bash
   npm run dev
   # or
   dryrun-ci web
   ```

2. **Open [http://localhost:3000](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
```yaml
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
```yaml
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
```yaml
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:
```yaml
variables:
  NODE_ENV: "production"
  API_URL: "https://api.example.com"
```

### Job Dependencies
Control job execution order:
```yaml
deploy_job:
  dependencies:
    - build_job
    - test_job
```

### Conditional Execution
Run jobs based on conditions:
```yaml
deploy_job:
  only:
    - main
  when: manual
```

### Artifacts
Share files between jobs:
```yaml
build_job:
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour
```

## 🛠️ Development

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

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

### Development Commands
```bash
# 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](https://github.com/nektos/act) - Run GitHub Actions locally
- [GitLab Runner](https://docs.gitlab.com/runner/) - Official GitLab CI/CD runner
- [Nixpacks](https://nixpacks.com/) - App source + Nix packages + Docker

## 🔗 Links

- **NPM Package:** [npmjs.com/package/dryrun-ci](https://npmjs.com/package/dryrun-ci)
- **Documentation:** [docs/](./docs/)
- **Issues:** [GitHub Issues](https://github.com/Asimatic-Labs/dryrun/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!