Initial commit: add .gitignore and README
This commit is contained in:
defiQUG
247
CI_CD_MIGRATION_GUIDE.md
Normal file
247
CI_CD_MIGRATION_GUIDE.md
Normal file
@@ -0,0 +1,247 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user