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

Use this template

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

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

Set up pre-commit hooks

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

Configure GitHub Token

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

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

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

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"

Push and Create PR

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

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

Check Versions

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

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

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

Enable Debug Logging

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

Use Debug Endpoints

# Health check
curl http://localhost:8000/health

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

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

Release Creation Fails
- Verify GitHub token permissions
- Check branch protection rules
- Ensure commit messages follow convention
- Verify git user configuration
Version Not Incrementing
- Check commit message format
- Verify branch configuration in pyproject.toml
- Check semantic-release logs in GitHub Actions

Workflow Debugging

Enable workflow debug logging:

env:
  ACTIONS_RUNNER_DEBUG: true
  ACTIONS_STEP_DEBUG: true

📊 Metrics and Monitoring

Available Metrics

Application Metrics (at /metrics)
- Request counts by endpoint
- Response times (p50, p95, p99)
- Error rates and types
- Active connections
- Resource utilization

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

Prometheus Configuration

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

Grafana Dashboard
- Import provided dashboard template
- Configure Prometheus data source
- Set up alerting rules

Health Checks

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

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

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Make your changes
Commit using conventional commits (git commit -m "feat: add amazing feature")
Push to the branch (git push origin feature/amazing-feature)
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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

FastAPI CI/CD Template

📑 Table of Contents

🌟 Features

📋 Prerequisites

🚀 Quick Start

🔄 Workflow Guide

Development Workflow

Version Management

🐛 Debugging Guide

Local Debugging

Common Issues

📊 Metrics and Monitoring

Available Metrics

Monitoring Setup

Health Checks

🔒 Environment Variables

🤝 Contributing

🔐 Security

🧪 Testing

🚨 Error Handling

Features

Usage

Generate a QR Code

Workflow Debugging Commands

Files

README.md

Latest commit

History

README.md

File metadata and controls

FastAPI CI/CD Template

📑 Table of Contents

🌟 Features

📋 Prerequisites

🚀 Quick Start

🔄 Workflow Guide

Development Workflow

Version Management

🐛 Debugging Guide

Local Debugging

Common Issues

📊 Metrics and Monitoring

Available Metrics

Monitoring Setup

Health Checks

🔒 Environment Variables

🤝 Contributing

🔐 Security

🧪 Testing

🚨 Error Handling

Features

Usage

Generate a QR Code

Workflow Debugging Commands