FastAPI CI/CD Template

A production-ready FastAPI template with robust CI/CD pipeline, semantic versioning, and best practices.

📑 Table of Contents

• Features
• Prerequisites
• Quick Start
• Development Guide
• Workflow Guide
• Debugging Guide
• Metrics and Monitoring
• Environment Variables
• License
• Contributing
• Security
• Docker Support
• API Documentation
• Performance
• Testing
• Error Handling

🌟 Features

• FastAPI-based RESTful API
• Poetry for dependency management
• Comprehensive CI/CD pipeline with GitHub Actions
• Semantic versioning and automated releases
• Automated changelog generation
• Code quality checks (Black, Commitlint)
• Test coverage reporting
• Prometheus metrics integration
• Structured logging with structlog
• Automated beta and release candidate versioning
• Branch-specific release configurations
• Detailed debugging and monitoring capabilities

📋 Prerequisites

• Python 3.9 or higher
• Poetry (Python package manager)
• Git
• Node.js 18+ (for commitlint)
• GitHub Personal Access Token (PAT) with repo scope

🚀 Quick Start

1. Use this template

   # Clone the repository
   git clone https://github.com/yourusername/fast-api-ci-cd
   cd fast-api-ci-cd

2. Install dependencies

   # Install Poetry
   curl -sSL https://install.python-poetry.org | python3 -
   
   # Install project dependencies
   poetry install
   
   # Install commitlint
   npm install -g @commitlint/cli @commitlint/config-conventional
   
   # Install semantic-release
   pip install python-semantic-release==9.15.0

3. Set up pre-commit hooks

   # Install pre-commit hooks
   poetry run pre-commit install
   poetry run pre-commit install --hook-type commit-msg

4. Configure GitHub Token

   # Add to your environment or .env file
   export GH_TOKEN=your_github_pat_token

5. Run the application

   # Development server with hot reload
   poetry run uvicorn app.main:app --reload --log-level debug
   
   # Production server
   poetry run uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

🔄 Workflow Guide

Development Workflow

1. Start a New Feature/Fix

   # Create a new branch
   git checkout develop
   git pull origin develop
   git checkout -b feature/your-feature  # or fix/your-fix

2. Make Changes and Commit

   # Stage changes
   git add .
   
   # Commit with conventional commit message
   git commit -m "feat(scope): add amazing feature"
   # or
   git commit -m "fix(scope): resolve specific issue"

3. Push and Create PR

   git push origin feature/your-feature
   # Create PR to develop branch via GitHub UI

4. Release Process

   # Beta releases (from develop)
   git checkout develop
   git pull origin develop
   # CI will automatically create beta release
   
   # Release candidates (from release/*)
   git checkout -b release/1.3.0
   git push origin release/1.3.0
   # CI will automatically create RC release
   
   # Final release (from main)
   # Create PR from develop to main
   # CI will create final release after merge

Version Management

1. Check Versions

   # Current version
   poetry run semantic-release print-version --current
   
   # Next version
   poetry run semantic-release print-version --next

2. Manual Release Trigger

   # Via GitHub Actions UI:
   # - Set prerelease: true/false
   # - Set prerelease_token: beta/rc/alpha
   # - Set force: patch/minor/major
   # - Set build_metadata: (optional)

🐛 Debugging Guide

Local Debugging

1. Enable Debug Logging

   # Run with debug logging
   poetry run uvicorn app.main:app --reload --log-level debug

2. Use Debug Endpoints

   # Health check
   curl http://localhost:8000/health
   
   # Debug info (development only)
   curl http://localhost:8000/debug/info

3. Troubleshoot CI/CD

   # Local semantic-release dry run
   poetry run semantic-release print-version --next
   
   # Verify git configuration
   git config --list
   
   # Check GitHub token
   gh auth status

Common Issues

1. Release Creation Fails

   • Verify GitHub token permissions
   • Check branch protection rules
   • Ensure commit messages follow convention
   • Verify git user configuration

2. Version Not Incrementing

   • Check commit message format
   • Verify branch configuration in pyproject.toml
   • Check semantic-release logs in GitHub Actions

3. Workflow Debugging

   • Enable workflow debug logging:

     env:
       ACTIONS_RUNNER_DEBUG: true
       ACTIONS_STEP_DEBUG: true

📊 Metrics and Monitoring

Available Metrics

1. Application Metrics (at /metrics)

   • Request counts by endpoint
   • Response times (p50, p95, p99)
   • Error rates and types
   • Active connections
   • Resource utilization

2. Custom Business Metrics

   # Example metric registration
   REQUEST_COUNT = Counter('http_requests_total', 'Total HTTP requests')
   
   # Example usage in endpoint
   @app.get("/")
   async def root():
       REQUEST_COUNT.inc()
       return {"message": "Hello World"}

Monitoring Setup

1. Prometheus Configuration

   scrape_configs:
     - job_name: 'fastapi'
       scrape_interval: 10s
       static_configs:
         - targets: ['localhost:8000']

2. Grafana Dashboard

   • Import provided dashboard template
   • Configure Prometheus data source
   • Set up alerting rules

Health Checks

1. Endpoints

   # Basic health check
   curl http://localhost:8000/health
   
   # Detailed health status
   curl http://localhost:8000/health/detail
   
   # Readiness probe
   curl http://localhost:8000/ready

2. Custom Health Checks

   # Example custom health check
   @app.get("/health/custom")
   async def custom_health():
       return {
           "status": "healthy",
           "checks": {
               "database": "connected",
               "cache": "available"
           }
       }

🔒 Environment Variables

Required environment variables:

• GH_TOKEN: GitHub token for releases (CI/CD)
• LOG_LEVEL: Logging level (debug/info/warning/error)
• PORT: Application port (default: 8000)
• WORKERS: Number of worker processes (default: 1)
• METRICS_ENABLED: Enable/disable Prometheus metrics (true/false)

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Commit using conventional commits (git commit -m "feat: add amazing feature")
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

🔐 Security

• All endpoints are rate-limited
• Input validation using Pydantic models
• CORS middleware configured
• Structured logging for audit trails
• Automated security scanning in CI/CD
• Signed commits required

🧪 Testing

# Run tests with coverage
poetry run pytest --cov=app tests/

# Generate coverage report
poetry run coverage html

# Run specific test file
poetry run pytest tests/test_specific.py -v

# Run tests with logging
poetry run pytest --log-cli-level=DEBUG

🚨 Error Handling

The API implements standardized error responses:

• 400: Bad Request - Invalid input
• 404: Not Found - Resource doesn't exist
• 429: Too Many Requests - Rate limit exceeded
• 500: Internal Server Error - Server-side issues

Custom error handling:

@app.exception_handler(CustomException)
async def custom_exception_handler(request: Request, exc: CustomException):
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "message": exc.message,
            "error_code": exc.error_code,
            "details": exc.details
        }
    )

Features

• Generate QR codes from URLs
• Custom QR code colors (fill and background)
• Customizable QR code size and border
• Base64 encoded output
• Error handling with descriptive messages
• API documentation with Swagger UI
• Prometheus metrics for monitoring
• Structured logging with JSON format
• CI/CD pipeline with automated testing and releases
• Semantic versioning with automated changelog

Usage

Generate a QR Code

curl -X POST "http://localhost:8000/api/v1/qr-code/generate" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://example.com",
       "fill_color": "#000000",
       "background_color": "#FFFFFF",
       "box_size": 10,
       "border": 4
     }'

The response will contain a base64 encoded QR code image:

{
    "qr_code": "base64_encoded_image_data"
}

You can customize the QR code appearance:

• fill_color: The color of the QR code pattern (default: "#000000" - black)
• background_color: The color of the QR code background (default: "#FFFFFF" - white)
• box_size: Size of each QR code box in pixels (default: 10, range: 1-100)
• border: Size of the QR code border in boxes (default: 4, range: 0-20)

Workflow Debugging Commands

# List recent workflow runs
gh run list --limit 5

# Watch a specific workflow run
gh run watch

# View details of the latest workflow run
gh run view

# View a specific workflow run by ID
gh run view <run-id>

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

# List failed workflow runs
gh run list --status failed

# Download workflow artifacts
gh run download <run-id>

# Track workflow progress
gh run list --limit 1 --watch

# View workflow run details in browser
gh run view --web

These commands help you:

• Monitor workflow progress in real-time
• Debug failed workflows
• View detailed logs
• Track version creation
• Verify workflow triggers
• Download artifacts for inspection