docs/CI_CD_PILOT_PROJECTS.md

CI/CD Pilot Projects

Date: 2025-01-27 Purpose: Guide for selecting and migrating pilot projects to unified CI/CD Status: Implementation Guide

---

Overview

This document identifies candidate projects for CI/CD pilot migration and provides step-by-step migration instructions.

---

Pilot Project Selection Criteria

Ideal Candidates

1. Active projects with regular commits
2. TypeScript/Node.js projects (matches template)
3. Well-tested projects (have test suites)
4. Medium complexity (not too simple, not too complex)
5. Team availability for feedback

---

Recommended Pilot Projects

High Priority (Start Here)

1. workspace-shared (New project)

   • Why: New project, clean slate
   • Complexity: Low
   • Risk: Low
   • Benefits: Validates template for monorepo

2. dbis_core (Active project)

   • Why: Core project, high visibility
   • Complexity: Medium
   • Risk: Medium
   • Benefits: Validates for large TypeScript project

3. the_order (Active monorepo)

   • Why: Monorepo structure, good test case
   • Complexity: High
   • Risk: Medium
   • Benefits: Validates monorepo CI/CD patterns

Medium Priority

4. Sankofa/api (Backend service)

   • Why: API service, common pattern
   • Complexity: Medium
   • Risk: Low

5. no_five (DeFi project)

   • Why: Different domain, validates template flexibility
   • Complexity: Medium
   • Risk: Medium

---

Migration Steps

Step 1: Prepare Project

1. Review current CI/CD (if exists)

   • Document current workflow
   • Identify project-specific requirements
   • Note any custom steps

2. Update project structure (if needed)

   • Ensure package.json has required scripts
   • Verify test setup
   • Check build configuration

Step 2: Create Workflow File

1. Copy template: .github/workflows/ci-pilot-template.yml
2. Rename: ci-<project-name>.yml
3. Update paths: Replace project-name with actual project path
4. Customize: Add project-specific steps if needed

Step 3: Test Locally

1. Install act (GitHub Actions local runner):

   brew install act  # macOS
   # or
   curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
   

2. Test workflow:

   act -W .github/workflows/ci-<project-name>.yml
   

Step 4: Deploy

1. Commit workflow file
2. Push to branch
3. Monitor first run
4. Fix any issues
5. Merge to main

Step 5: Gather Feedback

1. Monitor for 1-2 weeks
2. Collect feedback from team
3. Document issues and improvements
4. Refine template

---

Project-Specific Examples

Example 1: workspace-shared

Workflow: .github/workflows/ci-workspace-shared.yml

name: CI - Workspace Shared

on:
  push:
    branches: [main, develop]
    paths:
      - 'workspace-shared/**'
  pull_request:
    branches: [main, develop]
    paths:
      - 'workspace-shared/**'

jobs:
  lint:
    name: Lint
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: ./workspace-shared
    # ... rest of template

Example 2: dbis_core

Workflow: .github/workflows/ci-dbis-core.yml

name: CI - DBIS Core

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

jobs:
  lint:
    name: Lint
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: ./dbis_core
    # ... rest of template

---

Migration Checklist

Pre-Migration

• Review current CI/CD (if exists)
• Document project-specific requirements
• Verify project has required scripts (lint, test, build)
• Test scripts locally

Migration

• Copy template workflow
• Customize for project
• Test workflow locally (if possible)
• Commit workflow file
• Push to branch
• Monitor first run
• Fix any issues

Post-Migration

• Monitor for 1-2 weeks
• Gather team feedback
• Document issues
• Refine template based on feedback
• Update documentation

---

Common Customizations

Adding Database Tests

test:
  # ... existing steps
  - name: Start database
    run: docker-compose up -d postgres

  - name: Run tests
    run: pnpm test
    env:
      DATABASE_URL: postgresql://user:pass@localhost:5432/testdb

Adding Docker Build

build:
  # ... existing steps
  - name: Build Docker image
    run: docker build -t project-name:latest .

  - name: Push to registry
    if: github.ref == 'refs/heads/main'
    run: docker push project-name:latest

Adding Deployment

deploy:
  needs: [lint, test, build]
  runs-on: ubuntu-latest
  if: github.ref == 'refs/heads/main'
  steps:
    - uses: actions/checkout@v4
    - name: Deploy
      run: ./scripts/deploy.sh

---

Feedback Collection

Questions to Ask

1. Workflow execution:

   • Are workflows running correctly?
   • Any failures or errors?
   • Performance issues?

2. Developer experience:

   • Is feedback timely?
   • Are error messages clear?
   • Any missing checks?

3. Template completeness:

   • Missing any common steps?
   • Any unnecessary steps?
   • Suggestions for improvements?

---

Next Steps

1. Select 3-5 pilot projects
2. Migrate first project (workspace-shared recommended)
3. Monitor and gather feedback
4. Refine template
5. Migrate remaining pilots
6. Roll out to all projects

---

Last Updated: 2025-01-27