# CI Pipeline Setup Guide

## 📋 Current Status

✅ **Simplified CI** - `ci.yml` (Active)
- No external dependencies required
- Runs on all PRs and pushes to main/develop
- Core testing, linting, and validation

⏸️ **Full CI** - `ci-full.yml` (Disabled)
- Includes Codecov integration
- Manual trigger only until secrets are configured

⏸️ **HF Deployment** - `deploy_space.yml` (Disabled) 
- Manual trigger only until HF secrets are configured

✅ **Documentation** - `docs.yml` (Active)
- Works without external dependencies

✅ **GitHub Flow** - `github-flow.yml` (Active)
- Branch management and flow automation

## 🚀 Simplified CI Pipeline Features

The current active pipeline (`ci.yml`) includes:

### Core Testing Jobs
- **Unit Tests** - pytest with coverage reporting
- **Integration Tests** - e2e tests and task management validation  
- **Code Quality** - ruff linting, black formatting, mypy type checking
- **Security** - basic bandit security scanning
- **Structure Validation** - project file and directory checks
- **PR Checks** - title format and branch naming validation

### Key Benefits
- ✅ No external secrets required
- ✅ Fast feedback loop
- ✅ Comprehensive testing
- ✅ Local artifact uploads for coverage and security reports
- ✅ Graceful degradation (warnings instead of failures for non-critical checks)

### Artifacts Generated
- Coverage reports (HTML format, 7-day retention)
- Security scan reports (JSON format, 7-day retention)

## 🔧 When You're Ready to Enable Full Features

### 1. Enable Codecov Integration
Add these secrets to your repository settings:
- `CODECOV_TOKEN` - Get from codecov.io

Then uncomment the triggers in `ci-full.yml`:
```yaml
on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]
    types: [opened, synchronize, reopened, ready_for_review]
```

### 2. Enable HF Deployment
Add these secrets to your repository settings:
- `HF_TOKEN` - Your Hugging Face API token
- `HF_USERNAME` - Your Hugging Face username

Then uncomment the triggers in `deploy_space.yml`:
```yaml
on:
  push:
    branches: [ main ]
  workflow_dispatch:
```

### 3. Optional: Add Variables
In your repository settings, you can add these variables:
- `HF_SPACE_NAME` - Custom space name (defaults to 'kgraph-mcp-demo')

## 🧪 Testing the Current Setup

To test the simplified pipeline:

1. **Create a test branch:**
   ```bash
   just task-branch 999
   # or manually: git checkout -b feat/999_test_ci_pipeline
   ```

2. **Make a small change and push:**
   ```bash
   echo "# Test CI" >> test_ci.md
   git add test_ci.md
   git commit -m "test: verify simplified CI pipeline"
   git push -u origin feat/999_test_ci_pipeline
   ```

3. **Create a PR:**
   ```bash
   just commit-and-pr
   # or manually with gh CLI
   ```

4. **Monitor the workflow runs in GitHub Actions tab**

## 📊 Expected Workflow Results

The simplified CI should complete successfully with:
- ✅ Unit tests passing
- ✅ Code quality checks passing  
- ✅ Basic security scan completing
- ✅ Project structure validation passing
- ✅ Coverage and security reports uploaded as artifacts

## 🚨 Troubleshooting

### Common Issues
1. **Python setup fails** - Check if requirements.txt exists
2. **Tests fail** - Review test logs and ensure test files exist
3. **Linting fails** - Run `just lint` locally first
4. **Structure validation fails** - Ensure all required files/directories exist

### Quick Fixes
```bash
# Fix most issues locally first
just setup           # Setup environment
just check           # Run all checks
just pre-commit      # Pre-commit validation
```

## 📈 Next Steps

1. Test the simplified pipeline with a small PR
2. Add required secrets when ready for full features
3. Monitor initial runs for any remaining issues
4. Gradually enable additional features (Codecov, HF deployment)

The simplified pipeline gives you immediate CI/CD capability while you set up the external integrations at your own pace.