docs/CI_CD_MIGRATION_GUIDE.md

# CI/CD Migration Guide

**Last Updated**: 2025-01-27
**Purpose**: Guide for migrating projects to unified CI/CD pipeline templates

---

## Overview

This guide provides step-by-step instructions for migrating existing projects to use the unified CI/CD pipeline templates.

---

## Unified CI/CD Pipeline

### Pipeline Stages

1. **Lint & Format** - Code quality checks
2. **Type Check** - TypeScript/Solidity type checking
3. **Test** - Unit and integration tests
4. **Build** - Compile and build artifacts
5. **Security Scan** - Dependency and code scanning
6. **Deploy** - Deployment to environments

### Template Location
- **Template**: `.github/workflows/ci.yml`
- **Location**: Workspace root

---

## Migration Steps

### Step 1: Review Current CI/CD

For each project:
1. Check for existing `.github/workflows/` directory
2. Review current CI/CD configuration
3. Identify project-specific requirements
4. Document custom steps

### Step 2: Create Project-Specific Workflow

1. Copy base template: `.github/workflows/ci.yml`
2. Create project-specific workflow: `.github/workflows/ci-<project>.yml`
3. Customize for project needs
4. Test locally first

### Step 3: Integrate with Project

1. Add workflow file to project
2. Update project scripts if needed
3. Test workflow execution
4. Monitor build results

### Step 4: Update Documentation

1. Document project-specific CI/CD configuration
2. Update README with CI/CD information
3. Document deployment process

---

## Project-Specific Examples

### TypeScript/Node.js Project

```yaml
name: CI - Project Name

on:
  push:
    branches: [main, develop]
    paths:
      - 'project-name/**'
  pull_request:
    branches: [main, develop]
    paths:
      - 'project-name/**'

jobs:
  lint:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: ./project-name
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: pnpm install
      - run: pnpm lint

  test:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: ./project-name
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: pnpm install
      - run: pnpm test

  build:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: ./project-name
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: pnpm install
      - run: pnpm build
```

### Solidity/Foundry Project

```yaml
name: CI - Solidity Project

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: foundry-actions/foundry-toolchain@v1
      - run: forge test
      - run: forge fmt --check

  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: foundry-actions/foundry-toolchain@v1
      - run: forge build
```

---

## Migration Checklist

### Pre-Migration
- [ ] Review current CI/CD setup
- [ ] Identify project-specific requirements
- [ ] Document current build/test process
- [ ] Review project dependencies

### Migration
- [ ] Create workflow file
- [ ] Configure project-specific settings
- [ ] Test workflow locally (act tool)
- [ ] Create PR with workflow changes
- [ ] Verify workflow runs successfully

### Post-Migration
- [ ] Monitor workflow execution
- [ ] Fix any issues
- [ ] Update documentation
- [ ] Remove old CI/CD configuration (if applicable)

---

## Common Customizations

### Environment Variables
```yaml
env:
  NODE_ENV: production
  DATABASE_URL: ${{ secrets.DATABASE_URL }}
  API_KEY: ${{ secrets.API_KEY }}
```

### Matrix Builds
```yaml
strategy:
  matrix:
    node-version: [18, 20, 22]
```

### Deployment Steps
```yaml
deploy:
  needs: [build, test]
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: Deploy to Azure
      run: |
        # Deployment commands
```

---

## Projects to Migrate

### High Priority
1. **dbis_core** - Core banking system
2. **the_order** - Identity platform
3. **smom-dbis-138** - Blockchain network

### Medium Priority
1. **Sankofa** - Cloud platform
2. **miracles_in_motion** - Web application
3. **Defi-Mix-Tooling projects** - DeFi tools

### Lower Priority
1. **Documentation projects** - Static sites
2. **Utility projects** - Scripts and tools

---

## Troubleshooting

### Common Issues

**Issue**: Workflow fails on dependency installation
- **Solution**: Check package.json, ensure all dependencies are listed

**Issue**: Tests fail in CI but pass locally
- **Solution**: Check environment variables, test database setup

**Issue**: Build fails due to missing environment variables
- **Solution**: Add secrets to GitHub repository settings

---

## Resources

- [GitHub Actions Documentation](https://docs.github.com/en/actions)
- [Turborepo CI/CD Guide](https://turbo.build/repo/docs/ci)
- [Project CI/CD Templates](../.github/workflows/)

---

**Last Updated**: 2025-01-27