mmmlabs-common 1.1.0
Cloud-agnostic utilities for MMMLabs services
License: MIT
Requires Python: >=3.11
Keywords: cloud, gcp, azure, aws, utilities, multi-cloud

# Complete CI/CD Strategy for MMMLabs Common

## Why GitHub + PyPI is the Best Choice

### ✅ **Cloud Agnostic Benefits**
- **Universal Access**: Works from any environment (GCP, Azure, AWS, on-premises)
- **No Vendor Lock-in**: Not tied to any specific cloud provider's artifact registry
- **Industry Standard**: Follows Python ecosystem best practices
- **Better Discoverability**: Public packages are easily found by developers

### ✅ **Deployment Strategy**
```
Development → Testing → Staging → Production
     ↓           ↓         ↓          ↓
   develop   Test PyPI   GitHub    PyPI + Release
   branch     (beta)    Packages   (stable)
```

## Complete Workflow Architecture

### 1. **Branch Strategy**
```
main (production)     ──→ PyPI releases + GitHub releases
  ↑
develop (staging)     ──→ Test PyPI + beta releases  
  ↑
feature/fix branches  ──→ PR validation only
```

### 2. **CI/CD Pipeline Components**

#### **Quality Gates** (Every PR/Push)
- ✅ Multi-Python version testing (3.11, 3.12)
- ✅ Multi-cloud provider testing (GCP, Azure, AWS)
- ✅ Code quality (Black, Flake8, isort, MyPy)
- ✅ Security scanning (Bandit, Safety, CodeQL)
- ✅ Dependency vulnerability checks
- ✅ Test coverage reporting

#### **Automated Publishing**
- 🚀 **Test PyPI**: Auto-publish from `develop` branch
- 🚀 **PyPI**: Auto-publish on version tags (`v*`)
- 🚀 **GitHub Releases**: Auto-create with changelog
- 🚀 **Documentation**: Auto-deploy to GitHub Pages

#### **Dependency Management**
- 🔄 Weekly automated dependency updates (Dependabot)
- 🛡️ Security vulnerability monitoring
- 📊 Dependency review on PRs

### 3. **Installation Methods**

```bash
# Production (from PyPI)
pip install mmmlabs-common[gcp]

# Development (from GitHub)
pip install git+https://github.com/mmmlabs/mmmlabs-common.git

# Specific version
pip install mmmlabs-common==1.2.3[azure]

# All cloud providers
pip install mmmlabs-common[all]
```

### 4. **Environment Configuration**

#### **Multi-Environment Setup**
```bash
# Development
CLOUD_PROVIDER=gcp
GCP_PROJECT_ID=mmmlabs-dev
GCP_STORAGE_BUCKET=mmmlabs-dev-storage

# Production  
CLOUD_PROVIDER=azure
AZURE_SUBSCRIPTION_ID=prod-subscription
AZURE_STORAGE_ACCOUNT=mmmLabsProdStorage
```

#### **Service Usage**
```python
# Auto-configured from environment
from mmmlabs import create_cloud_client
client = create_cloud_client()

# Manual configuration
client = create_cloud_client(
    provider='gcp',
    project_id='my-project',
    storage_bucket='my-bucket'
)
```

## Required GitHub Secrets

### **PyPI Publishing**
```bash
PYPI_API_TOKEN          # Production PyPI token
TEST_PYPI_API_TOKEN     # Test PyPI token
```

### **Cloud Provider Testing** (Optional)
```bash
# GCP
GCP_SA_KEY              # Service account JSON
GCP_TEST_PROJECT_ID     # Test project ID

# Azure
AZURE_SUBSCRIPTION_ID   # Subscription ID
AZURE_TENANT_ID         # Tenant ID
AZURE_CLIENT_ID         # App registration client ID
AZURE_CLIENT_SECRET     # App registration secret

# AWS
AWS_ACCESS_KEY_ID       # Access key
AWS_SECRET_ACCESS_KEY   # Secret key
```

## Repository Setup Checklist

### **1. Initial Repository Setup**
- [ ] Create repository: `mmmlabs/mmmlabs-common`
- [ ] Set up branch protection rules (main, develop)
- [ ] Configure repository settings and labels
- [ ] Add team members and reviewers

### **2. Code Quality Setup**
- [ ] Copy all workflow files to `.github/workflows/`
- [ ] Set up pre-commit hooks: `pre-commit install`
- [ ] Configure code quality tools (Black, Flake8, etc.)
- [ ] Enable CodeQL security scanning

### **3. Publishing Setup**
- [ ] Create PyPI account and generate API token
- [ ] Create Test PyPI account and generate API token
- [ ] Add secrets to GitHub repository
- [ ] Configure trusted publishing (optional)

### **4. Documentation Setup**
- [ ] Enable GitHub Pages
- [ ] Configure MkDocs for documentation
- [ ] Set up API reference generation
- [ ] Create usage examples and guides

### **5. Testing Setup**
- [ ] Write comprehensive tests
- [ ] Set up test environments for each cloud provider
- [ ] Configure integration tests (optional)
- [ ] Set up code coverage reporting

## Deployment Commands

### **Manual Release** (Emergency)
```bash
# Tag and push for release
git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

# Manual PyPI upload (if CI fails)
python -m build
python -m twine upload dist/*
```

### **Development Workflow**
```bash
# Feature development
git checkout -b feature/new-cloud-provider
# ... make changes ...
git commit -m "feat(aws): add AWS S3 storage implementation"
git push origin feature/new-cloud-provider
# Create PR to develop

# Release preparation
git checkout develop
git pull origin develop
git checkout -b release/v1.2.0
# ... update version, changelog ...
git commit -m "chore(release): prepare v1.2.0"
# Create PR to main

# Production release
git checkout main
git merge release/v1.2.0
git tag v1.2.0
git push origin main --tags
```

## Monitoring and Maintenance

### **Automated Monitoring**
- 📊 **GitHub Insights**: Track repository activity
- 🔍 **Security Alerts**: Dependabot security updates  
- 📈 **Download Statistics**: PyPI download metrics
- 🐛 **Error Tracking**: Integration with error monitoring

### **Regular Maintenance Tasks**
- 🔄 Weekly dependency updates review
- 🧪 Monthly integration test verification
- 📚 Quarterly documentation review
- 🔒 Security audit every 6 months

## Benefits of This Approach

### **For Developers**
- ✅ Easy installation: `pip install mmmlabs-common[gcp]`
- ✅ Clear documentation and examples
- ✅ Consistent API across cloud providers
- ✅ Type hints and IDE support

### **For Operations**
- ✅ Cloud provider flexibility
- ✅ Easy migration between providers
- ✅ Standardized configuration
- ✅ Comprehensive monitoring

### **For Business**
- ✅ Reduced vendor lock-in
- ✅ Lower switching costs
- ✅ Faster development cycles
- ✅ Better compliance options

This CI/CD strategy provides a robust, scalable, and maintainable approach to multi-cloud package development and deployment, ensuring your `mmmlabs-common` package remains truly cloud-agnostic while following industry best practices.