docs/ci-cd/README.md

CI/CD Pipeline Documentation

Overview

The FRED ML project uses GitHub Actions for comprehensive CI/CD automation. The pipeline includes multiple workflows for different purposes:

• Main CI/CD Pipeline (ci-cd.yml): Full deployment pipeline for main branch
• Pull Request Checks (pull-request.yml): Quality checks for PRs and development
• Scheduled Maintenance (scheduled.yml): Automated maintenance tasks
• Release Deployment (release.yml): Versioned releases and production deployments

Workflow Overview

🚀 Main CI/CD Pipeline (ci-cd.yml)

Triggers:

• Push to main or develop branches
• Pull requests to main branch
• Daily scheduled runs at 2 AM UTC

Jobs:

1. 🧪 Test & Quality: Linting, type checking, unit tests
2. 🔗 Integration Tests: AWS integration testing
3. 🚀 End-to-End Tests: Complete system testing
4. 🔒 Security Scan: Security vulnerability scanning
5. ⚡ Deploy Lambda: AWS Lambda function deployment
6. 🏗️ Deploy Infrastructure: AWS infrastructure deployment
7. 🎨 Deploy Streamlit: Streamlit Cloud deployment preparation
8. 📢 Notifications: Deployment status notifications

🔍 Pull Request Checks (pull-request.yml)

Triggers:

• Pull requests to main or develop branches
• Push to develop branch

Jobs:

1. 🔍 Code Quality: Formatting, linting, type checking
2. 🧪 Unit Tests: Unit test execution with coverage
3. 🔒 Security Scan: Security vulnerability scanning
4. 📦 Dependency Check: Outdated dependencies and security
5. 📚 Documentation Check: README and deployment docs validation
6. 🏗️ Build Test: Lambda package and Streamlit app testing
7. 💬 Comment Results: Automated PR comments with results

⏰ Scheduled Maintenance (scheduled.yml)

Triggers:

• Daily at 6 AM UTC: Health checks
• Weekly on Sundays at 8 AM UTC: Dependency updates
• Monthly on 1st at 10 AM UTC: Performance testing

Jobs:

1. 🏥 Daily Health Check: AWS service status monitoring
2. 📦 Weekly Dependency Check: Dependency updates and security
3. ⚡ Monthly Performance Test: Performance benchmarking
4. 🧹 Cleanup Old Artifacts: S3 cleanup and maintenance

🎯 Release Deployment (release.yml)

Triggers:

• GitHub releases (published)

Jobs:

1. 📦 Create Release Assets: Lambda packages, docs, test results
2. 🚀 Deploy to Production: Production deployment
3. 🧪 Production Tests: Post-deployment testing
4. 📢 Notify Stakeholders: Release notifications

Required Secrets

Configure these secrets in your GitHub repository settings:

AWS Credentials

AWS_ACCESS_KEY_ID=your_aws_access_key
AWS_SECRET_ACCESS_KEY=your_aws_secret_key

FRED API

FRED_API_KEY=your_fred_api_key

Environment Variables

The workflows use these environment variables:

AWS_REGION: us-west-2
S3_BUCKET: fredmlv1
LAMBDA_FUNCTION: fred-ml-processor
PYTHON_VERSION: '3.9'

Workflow Features

🔄 Automated Testing

• Unit Tests: pytest with coverage reporting
• Integration Tests: AWS service integration
• End-to-End Tests: Complete system validation
• Security Scans: Bandit security scanning
• Performance Tests: Load and performance testing

🏗️ Infrastructure as Code

• S3 Bucket: Automated bucket creation and configuration
• Lambda Function: Automated deployment and configuration
• EventBridge Rules: Quarterly scheduling automation
• SSM Parameters: Secure parameter storage

📊 Monitoring & Reporting

• Code Coverage: Automated coverage reporting to Codecov
• Test Results: Detailed test result artifacts
• Security Reports: Vulnerability scanning reports
• Performance Metrics: Performance benchmarking

🔒 Security

• Secret Management: Secure handling of API keys
• Vulnerability Scanning: Automated security checks
• Access Control: Environment-based deployment controls
• Audit Trail: Complete deployment logging

Deployment Process

Development Workflow

1. Create feature branch from develop
2. Make changes and push to branch
3. Create pull request to develop
4. Automated checks run on PR
5. Merge to develop after approval
6. Automated testing on develop branch

Production Deployment

1. Create pull request from develop to main
2. Automated checks and testing
3. Merge to main triggers production deployment
4. Lambda function updated
5. Infrastructure deployed
6. Production tests run
7. Notification sent

Release Process

1. Create GitHub release with version tag
2. Automated release asset creation
3. Production deployment
4. Post-deployment testing
5. Stakeholder notification

Monitoring & Alerts

Health Checks

• Daily AWS service status monitoring
• Lambda function availability
• S3 bucket accessibility
• EventBridge rule status

Performance Monitoring

• Monthly performance benchmarking
• Response time tracking
• Resource utilization monitoring
• Error rate tracking

Security Monitoring

• Weekly dependency vulnerability scans
• Security best practice compliance
• Access control monitoring
• Audit log review

Troubleshooting

Common Issues

Lambda Deployment Failures

# Check Lambda function status
aws lambda get-function --function-name fred-ml-processor --region us-west-2

# Check CloudWatch logs
aws logs describe-log-groups --log-group-name-prefix /aws/lambda/fred-ml-processor

S3 Access Issues

# Check S3 bucket permissions
aws s3 ls s3://fredmlv1 --region us-west-2

# Test bucket access
aws s3 cp test.txt s3://fredmlv1/test.txt

EventBridge Rule Issues

# Check EventBridge rules
aws events list-rules --name-prefix "fred-ml" --region us-west-2

# Test rule execution
aws events test-event-pattern --event-pattern file://event-pattern.json

Debug Workflows

Enable Debug Logging

Add to workflow:

env:
  ACTIONS_STEP_DEBUG: true
  ACTIONS_RUNNER_DEBUG: true

Check Workflow Logs

1. Go to GitHub repository
2. Click "Actions" tab
3. Select workflow run
4. View detailed logs for each job

Best Practices

Code Quality

• Use pre-commit hooks for local checks
• Maintain high test coverage (>80%)
• Follow PEP 8 style guidelines
• Use type hints throughout codebase

Security

• Never commit secrets to repository
• Use least privilege AWS IAM policies
• Regularly update dependencies
• Monitor security advisories

Performance

• Optimize Lambda function cold starts
• Use S3 lifecycle policies for cleanup
• Monitor AWS service quotas
• Implement proper error handling

Documentation

• Keep README updated
• Document deployment procedures
• Maintain architecture diagrams
• Update troubleshooting guides

Advanced Configuration

Custom Workflow Triggers

on:
  push:
    branches: [ main, develop ]
    paths: [ 'lambda/**', 'frontend/**' ]
  pull_request:
    branches: [ main ]
    paths-ignore: [ 'docs/**' ]

Environment-Specific Deployments

jobs:
  deploy:
    environment:
      name: ${{ github.ref == 'refs/heads/main' && 'production' || 'staging' }}
      url: ${{ steps.deploy.outputs.url }}

Conditional Job Execution

jobs:
  deploy:
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-latest

Support

For issues with the CI/CD pipeline:

1. Check workflow logs in GitHub Actions
2. Review this documentation
3. Check AWS CloudWatch logs
4. Contact the development team

Contributing

To contribute to the CI/CD pipeline:

1. Create feature branch
2. Make changes to workflow files
3. Test locally with act (GitHub Actions local runner)
4. Create pull request
5. Ensure all checks pass
6. Get approval from maintainers