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

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

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

env:
  NODE_ENV: production
  DATABASE_URL: ${{ secrets.DATABASE_URL }}
  API_KEY: ${{ secrets.API_KEY }}

Matrix Builds

strategy:
  matrix:
    node-version: [18, 20, 22]

Deployment Steps

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
• Turborepo CI/CD Guide
• Project CI/CD Templates

---

Last Updated: 2025-01-27