@cloudkinetix/bmad-enhanced/expansion-packs/ck-gitlab-cicd-automation/README.md

Cloud-Kinetix enhanced fork of BMAD-METHOD - Breakthrough Method of Agile AI-driven Development with robust versioning and unified validation.

# GitLab CI/CD Automation Expansion Pack

## 🚀 Overview

The **ck-gitlab-cicd-automation** expansion pack provides comprehensive GitLab CI/CD pipeline automation, monitoring, and debugging capabilities for BMAD Enhanced. It seamlessly integrates with other Cloud Kinetix expansion packs to deliver intelligent CI/CD management that works autonomously without interactive prompts.

### Key Features

✅ **Non-Interactive GitLab Operations** - All commands verified to work autonomously  
✅ **Intelligent Pipeline Monitoring** - Real-time status tracking and health assessment  
✅ **Advanced Failure Analysis** - Root cause analysis with actionable insights  
✅ **Cross-Pack Integration** - Seamless integration with JIRA, parallel development, and AI agents  
✅ **Comprehensive Reporting** - Rich dashboards and detailed failure reports  
✅ **Plan-Aware Automation** - Integration with BMAD workflow planning system  
✅ **NEW: Robust Fallback Strategies** - Automatic fallback from glab to API when commands fail  
✅ **NEW: Enhanced Job Log Retrieval** - Reliable trace using numeric job IDs  
✅ **NEW: Permission-Aware Operations** - Graceful degradation with limited access

## 📦 Installation

### Prerequisites

- GitLab repository with CI/CD enabled
- GitLab CLI (`glab`) installed and authenticated
- BMAD Enhanced v1.4.0 or later

### Install the Expansion Pack

```bash
# Install with BMAD Enhanced
npx @cloudkinetix/bmad-enhanced install --expansion-packs ck-gitlab-cicd-automation

# Or add to existing installation
npx @cloudkinetix/bmad-enhanced install --expansion-only --expansion-packs ck-gitlab-cicd-automation
```

### GitLab CLI Setup

```bash
# Authenticate with GitLab
glab auth login

# Verify authentication
glab auth status

# Set default project (optional)
glab config set gitlab.com/your-org/your-project
```

## 🎯 Core Components

### 🤖 GitLab CI/CD Agent

Primary agent for GitLab CI/CD operations with intelligent automation capabilities.

```bash
# Activate the agent
/glab

# Common agent tasks
/glab monitor pipeline status for main branch
/glab analyze recent failures and suggest fixes
/glab generate health report for last 7 days
/glab coordinate parallel development CI status
```

### 🛠️ Core Tasks

| Task                          | Purpose                        | Usage                                        |
| ----------------------------- | ------------------------------ | -------------------------------------------- |
| `monitor-pipeline-status`     | Real-time pipeline monitoring  | Track CI status across branches              |
| `analyze-pipeline-failures`   | Intelligent failure analysis   | Root cause analysis and recommendations      |
| `debug-ci-configuration`      | CI config troubleshooting      | Validate and optimize pipeline configuration |
| `generate-ci-health-report`   | Comprehensive health reporting | Team dashboards and metrics                  |
| `sync-ci-status-to-jira`      | JIRA integration               | Sync pipeline status to JIRA issues          |
| `coordinate-parallel-ci`      | Multi-worktree coordination    | Manage CI across parallel development        |
| `create-gitlab-workflow-plan` | Workflow planning              | Generate structured CI/CD plans              |

### 📊 Structured Workflows

| Workflow                      | Purpose                       | When to Use                         |
| ----------------------------- | ----------------------------- | ----------------------------------- |
| `gitlab-ci-debugging`         | Systematic issue resolution   | Pipeline failures and debugging     |
| `ci-health-monitoring`        | Continuous monitoring         | Proactive health management         |
| `integrated-development-flow` | Complete development workflow | Full feature development with CI/CD |

## 🔗 Integration Examples

### JIRA Integration

Automatic synchronization of CI/CD status with JIRA issues.

```bash
# Basic JIRA sync
sync-ci-status-to-jira --branch feature/AUTH-123

# Automatic sync for workflow
/glab sync pipeline status to JIRA for current branch

# Configure automatic updates
/jira configure CI status sync for project AUTH
```

**Example Workflow:**

1. Developer creates JIRA issue `AUTH-123: Implement user authentication`
2. Creates branch `feature/AUTH-123`
3. Pipeline status automatically syncs to JIRA issue
4. JIRA issue shows real-time CI status and links to pipeline

### Parallel Development Integration

Coordinate CI/CD across multiple git worktrees for parallel development.

```bash
# Assess parallel development CI health
coordinate-parallel-ci --mode assess

# Full coordination with recommendations
coordinate-parallel-ci --auto-recommendations true

# Monitor across all worktrees
/glab coordinate CI status across all parallel branches
```

**Example Scenario:**

```bash
# Setup parallel development
git worktree add ../feature-a feature/user-auth
git worktree add ../feature-b feature/payment-system

# Monitor CI across all worktrees
coordinate-parallel-ci --merge-target main --health-threshold 80

# Get merge readiness assessment
coordinate-parallel-ci --mode assess --generate-report true
```

### AI Agent Development Integration

Enhanced CI/CD for AI agent development workflows.

```bash
# Monitor agent testing pipelines
/glab monitor CI for AI agent development workflows

# Analyze agent performance test failures
analyze-pipeline-failures --focus agent-performance

# Generate agent CI health report
generate-ci-health-report --agent-focus true
```

## 📋 Usage Examples

### Daily CI Health Monitoring

```bash
# Morning health check
generate-ci-health-report --period 24h --format dashboard

# Check for any failing pipelines
monitor-pipeline-status --status failed --since "yesterday"

# Analyze and address failures
analyze-pipeline-failures --auto-fix-suggestions true
```

### Pipeline Debugging Workflow

```bash
# When a pipeline fails
analyze-pipeline-failures --pipeline-id 12345

# Debug configuration issues
debug-ci-configuration --branch feature/broken-build

# Generate debug report
/glab generate detailed debug analysis for pipeline 12345
```

### Feature Development with CI Integration

```bash
# Start feature development
/glab create workflow plan for feature development

# Monitor progress during development
monitor-pipeline-status --branch feature/new-feature --follow

# Coordinate with team using JIRA
sync-ci-status-to-jira --branch feature/new-feature --auto-update
```

## 🎛️ Configuration

### Environment Variables

```bash
# GitLab configuration
export GITLAB_TOKEN="your-gitlab-token"
export GITLAB_URL="https://gitlab.com"  # or your GitLab instance

# Integration settings
export JIRA_INTEGRATION_ENABLED="true"
export PARALLEL_DEV_INTEGRATION_ENABLED="true"

# Monitoring settings
export CI_HEALTH_THRESHOLD="80"
export PIPELINE_TIMEOUT="3600"
```

### Project Configuration

Create `.gitlab-ci-automation.yml` in your project root:

```yaml
# GitLab CI/CD Automation Configuration
automation:
  monitoring:
    enabled: true
    health_threshold: 80
    notification_channels:
      - slack
      - email

  integrations:
    jira:
      enabled: true
      project_key: "PROJ"
      auto_sync: true

    parallel_dev:
      enabled: true
      coordination_mode: "full"
      merge_target: "main"

  debugging:
    auto_analysis: true
    generate_reports: true
    retention_days: 30

  workflows:
    default_workflow: "integrated-development-flow"
    auto_plan_creation: true
```

## 📊 Reporting and Dashboards

### Health Dashboard

Generate comprehensive CI/CD health dashboards:

```bash
# Generate current health dashboard
generate-ci-health-report --format dashboard --output health-dashboard.md

# Real-time monitoring dashboard
/glab create real-time health dashboard

# Team dashboard with metrics
generate-ci-health-report --format team-dashboard --period 7d
```

### Failure Analysis Reports

```bash
# Detailed failure analysis
analyze-pipeline-failures --generate-report --period 24h

# Debug analysis for specific pipeline
analyze-pipeline-failures --pipeline-id 12345 --deep-analysis

# Trend analysis
analyze-pipeline-failures --trend-analysis --period 30d
```

### Integration Status Reports

```bash
# Overall integration health
/glab generate integration status report

# JIRA integration specific
sync-ci-status-to-jira --status-report

# Parallel development coordination report
coordinate-parallel-ci --generate-report --detailed
```

## 🔧 Advanced Usage

### Custom Workflow Creation

```bash
# Create custom CI/CD workflow plan
create-gitlab-workflow-plan --workflow-type setup --complexity complex

# Integration-focused workflow
create-gitlab-workflow-plan --workflow-type integration --integration-packs jira,parallel-dev

# Debugging workflow
create-gitlab-workflow-plan --workflow-type debugging --auto-recommendations
```

### Multi-Environment Coordination

```bash
# Monitor across environments
monitor-pipeline-status --environments dev,staging,prod

# Environment-specific health reports
generate-ci-health-report --environment production --period 7d

# Cross-environment failure analysis
analyze-pipeline-failures --cross-environment --correlation-analysis
```

### Automated Remediation

```bash
# Auto-fix common issues
debug-ci-configuration --auto-fix --backup-config

# Intelligent retry with analysis
monitor-pipeline-status --auto-retry --failure-analysis

# Proactive optimization
/glab optimize pipeline configuration based on performance trends
```

## 🚨 Troubleshooting

### Common Issues

#### GitLab CLI Authentication Problems

```bash
# Check authentication status
glab auth status

# Re-authenticate if needed
glab auth login --hostname gitlab.com

# Verify access to project
glab repo view
```

#### Pipeline Monitoring Issues

```bash
# Debug monitoring connectivity
monitor-pipeline-status --debug --verbose

# Check GitLab API access
glab api projects/:id/pipelines --paginate

# Validate configuration
debug-ci-configuration --validate-only
```

#### Integration Sync Failures

```bash
# Test JIRA connectivity
sync-ci-status-to-jira --test-connection

# Debug parallel development coordination
coordinate-parallel-ci --debug --dry-run

# Validate integration bridge
/glab test all integration connections
```

### Performance Optimization

```bash
# Analyze pipeline performance
generate-ci-health-report --performance-focus

# Optimize monitoring frequency
monitor-pipeline-status --optimize-polling

# Cache optimization
debug-ci-configuration --cache-analysis
```

### Enhanced Reliability (v1.1.0+)

The expansion pack now includes robust fallback strategies to handle common GitLab CLI failures:

#### Automatic Command Fallbacks

When `glab` commands fail (which happens frequently with permission issues), the pack automatically falls back to direct API calls:

```bash
# Enable debug mode to see fallback strategies in action
export GITLAB_DEBUG=true

# The pack will automatically try:
# 1. glab ci get → 2. glab ci list → 3. Direct API call
monitor-pipeline-status --branch main
```

#### Job Log Retrieval Fix

**Important**: Job logs now use numeric job IDs (not job names):

```bash
# ❌ Old way (fails): glab ci trace "job-name"
# ✅ New way (works): Automatic ID resolution

# The pack handles this automatically:
analyze-pipeline-failures  # Resolves job names to IDs internally
```

#### Permission-Aware Operations

The pack now validates permissions and gracefully degrades when access is limited:

```bash
# Test your GitLab permissions
validate_gitlab_permissions  # From gitlab-commands utility

# API fallback when permissions are limited
export GITLAB_TOKEN="your-token"  # Direct API access often works when glab fails
monitor-pipeline-status
```

### Debug Mode

Enable verbose debugging for all operations:

```bash
# New enhanced debug mode (v1.1.0+)
export GITLAB_DEBUG=true  # Shows command fallback attempts

# Legacy debug variables still supported
export GITLAB_CI_DEBUG=true
export BMAD_DEBUG=true

# Run commands with debug output
monitor-pipeline-status --debug
analyze-pipeline-failures --verbose --debug

# See which methods are being tried
GITLAB_DEBUG=true monitor-pipeline-status
```

## 📚 Integration Patterns

### Pattern 1: JIRA-Driven Development

```bash
# 1. Create JIRA issue and branch
/jira create issue "Implement user dashboard" --type Story --assignee @me
git checkout -b feature/PROJ-123-user-dashboard

# 2. Automatic CI monitoring with JIRA sync
/glab enable automatic JIRA sync for current branch

# 3. Development with real-time CI feedback
monitor-pipeline-status --branch current --jira-updates

# 4. Merge readiness assessment
/glab assess merge readiness with JIRA integration
```

### Pattern 2: Parallel Feature Development

```bash
# 1. Setup parallel development
git worktree add ../feature-auth feature/authentication
git worktree add ../feature-ui feature/ui-redesign

# 2. Coordinate CI across worktrees
coordinate-parallel-ci --setup --merge-target main

# 3. Monitor aggregate health
/glab monitor parallel development CI health

# 4. Plan coordinated integration
coordinate-parallel-ci --integration-plan --auto-recommendations
```

### Pattern 3: AI Agent Development

```bash
# 1. Create AI agent workflow plan
create-gitlab-workflow-plan --workflow-type setup --project-context ai-agent

# 2. Setup agent-specific CI monitoring
/glab configure monitoring for AI agent development

# 3. Performance regression detection
monitor-pipeline-status --agent-performance-focus

# 4. Agent testing coordination
/glab coordinate agent testing across environments
```

## 🔄 Workflow Integration

### BMAD Workflow Plans

The expansion pack integrates with BMAD's workflow planning system:

```bash
# Create comprehensive development workflow
create-gitlab-workflow-plan --bmad-integration --full-lifecycle

# Load workflow into BMAD system
/glab create and load development workflow plan

# Track progress with checkpoints
/glab track workflow progress with CI integration
```

### Cross-Pack Coordination

Seamless integration with other expansion packs:

```bash
# Multi-pack coordination
/glab coordinate with JIRA and parallel development packs

# Comprehensive project health
/glab generate cross-pack integration health report

# Unified workflow execution
/glab execute integrated workflow with all expansion packs
```

## 📈 Metrics and KPIs

### Key Performance Indicators

The expansion pack tracks important CI/CD metrics:

- **Pipeline Success Rate**: Percentage of successful pipeline executions
- **Mean Time to Recovery (MTTR)**: Average time to resolve pipeline failures
- **Build Duration**: Average pipeline execution time
- **Integration Health**: Cross-pack integration success rate
- **Team Productivity**: Developer impact and efficiency metrics

### Custom Metrics

```bash
# Define custom metrics
generate-ci-health-report --custom-metrics "deployment-frequency,lead-time"

# Track business impact
/glab track business metrics for CI/CD performance

# ROI analysis
generate-ci-health-report --roi-analysis --cost-optimization
```

## 🛡️ Security and Best Practices

### Security Configuration

```bash
# Secure GitLab token storage
glab auth login --secure-storage

# Validate security settings
debug-ci-configuration --security-audit

# Monitor for security issues
analyze-pipeline-failures --security-focus
```

### Best Practices

1. **Regular Health Monitoring**: Run daily health checks
2. **Proactive Failure Analysis**: Address issues before they impact development
3. **Integration Coordination**: Keep all expansion packs synchronized
4. **Performance Optimization**: Regular pipeline performance reviews
5. **Documentation**: Maintain up-to-date CI/CD documentation

## 🤝 Contributing

### Development Setup

```bash
# Clone the expansion pack for development
git clone <repo-url>
cd ck-gitlab-cicd-automation

# Install dependencies
npm install

# Run tests
npm test

# Validate expansion pack
npm run validate
```

### Testing

Tests are centralized in the main test directory for better CI/CD practices:

```bash
# Run all GitLab CI/CD tests
npm run test:expansion:gitlab

# Run only integration tests
npm run test:expansion:gitlab:integration

# Run only validation tests (quick checks)
npm run test:expansion:gitlab:validation

# Run all expansion pack tests
npm run test:expansion:all

# Run tests with coverage
npm test

# Run specific test file
npx jest test/expansion-packs/ck-gitlab-cicd-automation/integration.test.js
```

Test files are located in:

- `test/expansion-packs/ck-gitlab-cicd-automation/integration.test.js` - Comprehensive feature tests
- `test/expansion-packs/ck-gitlab-cicd-automation/validation.test.js` - Quick validation tests

## 📞 Support

### Getting Help

- **Documentation**: [GitLab CI/CD Automation Docs](./docs/)
- **Issues**: [GitHub Issues](https://github.com/cloudkinetix/bmad-enhanced/issues)
- **Community**: [Cloud Kinetix Community](https://community.cloudkinetix.com)

### Common Support Scenarios

```bash
# Get help with specific commands
monitor-pipeline-status --help
analyze-pipeline-failures --help

# Access built-in documentation
/glab help
/glab examples

# Debug mode for troubleshooting
export GITLAB_CI_DEBUG=true
```

## 📄 License

This expansion pack is part of BMAD Enhanced and follows the same licensing terms.

---

## 🎉 Quick Start Checklist

- [ ] Install expansion pack: `npx @cloudkinetix/bmad-enhanced install --expansion-packs ck-gitlab-cicd-automation`
- [ ] Setup GitLab CLI: `glab auth login`
- [ ] Verify installation: `/glab help`
- [ ] Run health check: `generate-ci-health-report`
- [ ] Configure integrations (optional): JIRA, parallel-dev
- [ ] Create first workflow plan: `create-gitlab-workflow-plan`
- [ ] Start monitoring: `monitor-pipeline-status`

**You're ready to go! 🚀**

For questions or advanced usage scenarios, check the [examples directory](./docs/examples/) or reach out to the Cloud Kinetix community.