Skip to content

CI-CD-SETUP.md

Latest commit

 

History

History
310 lines (248 loc) · 8.71 KB

CI-CD-SETUP.md

File metadata and controls

310 lines (248 loc) · 8.71 KB

🚀 CI/CD Pipeline Summary

📊 Pipeline Status

CI/CD Pipeline Security Analysis Preview Deployments

🎯 What's Included

Your custom CI/CD pipeline includes:

✅ Core Features

  • Automated Quality Checks: Linting, type checking, and code formatting
  • Comprehensive Testing: Unit tests, integration tests, and E2E tests with Playwright
  • Security Scanning: Trivy vulnerability scanning, dependency audits, and secret detection
  • Multi-Environment Deployments: Development, Staging, and Production environments
  • Performance Monitoring: Lighthouse audits and bundle size analysis
  • Database Migrations: Automated migration execution post-deployment
  • Health Checks: Post-deployment validation and monitoring

🔄 Additional Workflows

  1. Preview Deployments - Automatic PR preview environments
  2. Security Analysis - Daily security scans and CodeQL analysis
  3. Dependency Updates - Weekly automated dependency updates
  4. Rollback Capability - Automatic rollback on deployment failures

🐳 Docker Support

  • Multi-stage Dockerfile for optimized builds
  • Docker Compose for local development
  • Container image building in CI/CD
  • Health checks and monitoring

📁 Files Created

Workflow Files (.github/workflows/)

├── ci-cd-pipeline.yml          # Main deployment pipeline
├── preview-deployment.yml      # PR preview deployments
├── security-analysis.yml       # Security and code quality
└── dependency-updates.yml      # Automated updates

Documentation (docs/)

├── CI-CD-PIPELINE.md          # Complete documentation
└── CI-CD-QUICK-REFERENCE.md   # Quick reference guide

Docker Files

├── Dockerfile                  # Production container
├── .dockerignore              # Docker ignore patterns
└── docker-compose.yml         # Local development setup

🚦 Pipeline Flow

┌─────────────┐
│ Code Push   │
└──────┬──────┘
       │
       ↓
┌─────────────────────────────────────┐
│ Setup & Cache Dependencies          │
└──────┬──────────────────────────────┘
       │
       ↓
┌─────────────────────────────────────┐
│ Parallel Execution                   │
├─────────────┬──────────┬────────────┤
│ Quality     │ Security │ Tests      │
│ Checks      │ Scanning │ (Unit+E2E) │
└─────┬───────┴────┬─────┴──────┬─────┘
      │            │            │
      └────────────┴────────────┘
                   │
                   ↓
         ┌─────────────────┐
         │ Build           │
         └────────┬────────┘
                  │
                  ↓
    ┌─────────────────────────┐
    │ Environment Deployments  │
    ├──────┬────────┬─────────┤
    │ Dev  │Staging │  Prod   │
    └──────┴────┬───┴─────────┘
                │
                ↓
    ┌───────────────────────┐
    │ Post-Deployment       │
    ├──────┬────────┬───────┤
    │  DB  │Perf.   │Health │
    │Migrate│Audit  │Checks │
    └──────┴────────┴───────┘

🔧 Setup Instructions

1. Configure GitHub Secrets

Go to: Settings → Secrets and variables → Actions → New repository secret

Required Secrets:

VERCEL_TOKEN              # Get from: https://vercel.com/account/tokens
VERCEL_ORG_ID             # Found in Vercel project settings
VERCEL_PROJECT_ID         # Found in Vercel project settings
PRODUCTION_DATABASE_URL   # PostgreSQL connection string

Optional Secrets:

CLOUDFLARE_ZONE_ID        # For DNS management
CLOUDFLARE_API_TOKEN      # Cloudflare API token
DOCKER_USERNAME           # Docker Hub username
DOCKER_PASSWORD           # Docker Hub token

2. Enable GitHub Actions

  1. Go to Settings → Actions → General
  2. Set "Actions permissions" to: Allow all actions and reusable workflows
  3. Enable "Allow GitHub Actions to create and approve pull requests"

3. Configure Branch Protection

For main branch:

  1. Go to Settings → Branches
  2. Add rule for main
  3. Enable:
    • ✅ Require status checks to pass
    • ✅ Require branches to be up to date
    • ✅ Status checks: quality-check, test, build
    • ✅ Require pull request reviews

For develop branch:

  • Same as above but without review requirement

4. Configure Environments

Create environments:

  1. Go to Settings → Environments
  2. Create: development, staging, production

For Production environment:

  • ✅ Required reviewers: Add team members
  • ✅ Wait timer: 5 minutes (optional)
  • ✅ Deployment branches: Only main

5. Local Development with Docker

# Start all services
docker-compose up -d

# Start with database tools (pgAdmin)
docker-compose --profile tools up -d

# View logs
docker-compose logs -f app

# Stop services
docker-compose down

# Clean up volumes
docker-compose down -v

Access points:

🎯 Usage Examples

Deploy to Development

git checkout develop
git pull
# Make changes
git add .
git commit -m "feat: add feature"
git push
# Automatically deploys to dev.tiqology.vercel.app

Deploy to Production

git checkout main
git merge develop
git push
# Deploys to staging → production (with approval)

Manual Deployment

# Using GitHub CLI
gh workflow run ci-cd-pipeline.yml \
  --ref main \
  -f environment=production \
  -f skip_tests=false

Create Preview Deployment

git checkout -b feature/new-feature
# Make changes
git push origin feature/new-feature
# Open PR → automatic preview deployment

📊 Monitoring

Check Pipeline Status

# List recent runs
gh run list --workflow=ci-cd-pipeline.yml

# Watch current run
gh run watch

# View logs
gh run view <run-id> --log

Application Health

# Production
curl https://tiqology.vercel.app/api/health

# Development
curl https://dev.tiqology.vercel.app/api/health

Performance Metrics

  • View Lighthouse reports in GitHub Actions artifacts
  • Check Vercel Analytics dashboard
  • Review bundle size in build logs

🔍 Troubleshooting

Common Issues

Build Failure:

# Check locally first
pnpm install
pnpm build

Test Failure:

# Run tests locally
pnpm test

# Run specific test
pnpm test -- <test-file>

Deployment Failure:

# Verify secrets
gh secret list

# Check Vercel status
vercel login
vercel ls

📚 Documentation

🎉 Key Benefits

✅ Automated: No manual deployment steps ✅ Fast: Parallel execution, ~18 minutes total ✅ Secure: Multiple security scanning layers ✅ Reliable: Comprehensive testing before deployment ✅ Monitored: Health checks and performance audits ✅ Recoverable: Automatic rollback on failures ✅ Documented: Extensive guides and references

🚀 Next Steps

  1. ✅ Configure GitHub secrets
  2. ✅ Enable GitHub Actions
  3. ✅ Set up branch protection
  4. ✅ Configure environments
  5. ✅ Make your first deployment
  6. ✅ Monitor and optimize

📞 Support

For issues or questions:

Pipeline Version: 2.0
Last Updated: December 22, 2025
Status: ✅ Ready for Production