🚀 CI/CD + Semantic Release — FastAPI CRUD App

A production-ready FastAPI CRUD application with automated CI/CD pipelines

---

📋 Table of Contents

• ✨ Overview
• 🎯 Key Features
• 📁 Project Structure
• 🛠️ Tech Stack
• ⚙️ Installation
• 🔧 Configuration
• ▶️ Running the App
• 📡 API Usage
• 🧪 Tests
• 🔄 CI/CD Pipeline
• 🗺️ Roadmap
• 🤝 Contributing
• 📄 License
• 🙏 Acknowledgements

---

✨ Overview

This repository showcases a minimal, production-like FastAPI application with a complete Items CRUD system. It serves as a comprehensive reference for implementing robust CI/CD pipelines with semantic versioning and automation.

What's Inside?

• 🎯 FastAPI service with SQLModel models and PostgreSQL configuration
• 🏗️ Clean architecture with separated business logic layer
• 🤖 Automated releases using python-semantic-release
• ✅ Comprehensive CI checks: linting (ruff), testing (pytest), type checking (mypy)
• 📚 Auto-deployed documentation via MkDocs
• 🐳 Docker support with helper scripts for builds

Perfect for: Learning semantic-release integration with Python and building reliable CI/CD pipelines that automate versioning, changelogs, and publishing.

---

🎯 Key Features

🏛️ Architecture Clean FastAPI app with SQLModel + SQLAlchemy Well-separated service layer PostgreSQL for production, SQLite for tests	🔬 Quality Assurance Full test coverage with pytest Unit and integration tests Type checking with mypy
🤖 Automation Semantic-release for versioning Automated changelog generation GitHub Actions CI/CD pipeline	🐳 Deployment Docker containerization GHCR image publishing Trivy security scanning Automated Render deployment

---

📁 Project Structure

.
├── 🔧 .github/
│   └── workflows/
│       ├── ci.yml            # CI checks — lint, tests, docs
│       ├── release.yml       # Automated releases
│       └── cd.yml            # Container builds & deployment
│
├── 📦 app/
│   ├── main.py               # FastAPI application entry point
│   ├── database.py           # Database configuration
│   ├── logging_config.py     # Centralized logging
│   ├── models/               # SQLModel data models
│   ├── routes/               # API route handlers
│   ├── schemas/              # Pydantic schemas
│   └── services/             # Business logic layer
│
├── 📚 docs/                  # MkDocs documentation
├── 🧪 tests/                 # Test suite (pytest)
├── 📜 scripts/               # Helper scripts
├── 🐳 Dockerfile             # Container definition
├── 📝 CHANGELOG.md           # Auto-generated changelog
├── ⚙️ pyproject.toml         # Project configuration
└── 📖 README.md              # You are here!

---

🛠️ Tech Stack

Category	Technologies
Language
Framework
Database
ORM
CI/CD
Container
Docs
Tools

---

⚙️ Installation

Prerequisites: macOS/Linux with zsh. This project uses uv (Astral) for fast dependency management.

📥 Step 1: Clone the Repository

git clone https://github.com/MichAdebayo/CI-CD-semantic-release.git
cd CI-CD-semantic-release

🔨 Step 2: Install uv (Astral)

curl -LsSf https://astral.sh/uv/install.sh | sh

📦 Step 3: Install Dependencies

# Sync all dependencies to virtual environment
uv sync --dev

🔐 Step 4: Configure Environment (Optional)

# Copy example environment file
cp .env.example .env

# Edit with your values
# DATABASE_URL="SET_YOUR_DB_URL"
# DEBUG_MODE="SET_DEBUG_MODE"

---

🔧 Configuration

🌍 Environment Variables

Variable	Description	Required
DATABASE_URL	PostgreSQL connection string	✅ Production
DEBUG_MODE	Enable FastAPI debug mode	❌ Optional
GITHUB_TOKEN	Token for semantic-release	✅ CI/CD

🔒 CI/CD Secrets

Configure these in your GitHub repository settings:

🤖 GitHub App Configuration (Click to expand)

Required Secrets:

• APP_ID — GitHub App ID for release workflow
• APP_PRIVATE_KEY_B64 — Base64-encoded private key
• DEPLOY_URL — Render webhook URL
• GHCR_PAT / GHCR_USER — Optional: manual GHCR credentials

Setup Steps:

1. Navigate to GitHub → Settings → Developer settings → GitHub Apps
2. Click New GitHub App
3. Configure permissions: contents: write, packages: write, actions: write
4. Generate a private key and encode it:

   base64 -i private-key.pem | pbcopy

5. Add secrets to your repository

⚠️ Security Note: Never commit secrets to the repository. Use .env.example with placeholders only.

---

▶️ Running the App

🚀 Development Server (Hot Reload)

# FastAPI dev mode
uv run fastapi dev app/main.py

# Or with uvicorn directly
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

🐳 Production (Docker)

# Build image
./scripts/docker-build.sh myorg/items:latest

# Run container
docker run -p 8000:8000 \
  --env DATABASE_URL="postgresql://..." \
  myorg/items:latest

🌐 Access the Application

• API Root: http://127.0.0.1:8000/
• Health Check: http://127.0.0.1:8000/health
• Interactive Docs: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

---

📡 API Usage

📌 Endpoints Overview

Method	Endpoint	Description
GET	/	Root endpoint
GET	/health	Health check
POST	/items	Create new item
GET	/items	List all items
GET	/items/{id}	Get item by ID
PUT	/items/{id}	Update item
DELETE	/items/{id}	Delete item

💡 Example Requests

Create Item

curl -X POST http://127.0.0.1:8000/items \
  -H "Content-Type: application/json" \
  -d '{"nom":"Keyboard","prix":49.99}'

Get All Items

curl http://127.0.0.1:8000/items

Get Single Item

curl http://127.0.0.1:8000/items/1

Update Item

curl -X PUT http://127.0.0.1:8000/items/1 \
  -H "Content-Type: application/json" \
  -d '{"prix":59.99}'

Delete Item

curl -X DELETE http://127.0.0.1:8000/items/1

---

🧪 Tests

🏃 Running Tests

# Run all tests
uv run pytest -q

# With coverage
uv run pytest --cov=app tests/

# Verbose output
uv run pytest -v

📊 Test Coverage

The test suite includes:

• ✅ Unit tests for models and service layer
• ✅ Integration tests for API endpoints
• ✅ Edge case handling and error scenarios
• ✅ In-memory SQLite for fast test execution

---

🔄 CI/CD Pipeline

🏗️ Workflow Architecture

graph LR
    A[Push/PR] --> B[CI Workflow]
    B --> C{Tests Pass?}
    C -->|Yes| D[Release Workflow]
    C -->|No| E[Fail]
    D --> F{Main Branch?}
    F -->|Yes| G[CD Workflow]
    F -->|No| H[Dry Run]
    G --> I[Build Docker]
    I --> J[Push to GHCR]
    J --> K[Security Scan]
    K --> L[Deploy to Render]

Loading

📋 Workflow Details

Workflow	Trigger	Actions
CI ci.yml	Push/PR to main, develop	• Install dependencies • Run linting (ruff) • Execute tests (pytest) • Type check (mypy) • Deploy docs (MkDocs) • Trigger release workflow
Release release.yml	Called by CI	• Authenticate via GitHub App • Run semantic-release • Generate changelog • Create GitHub Release • Trigger CD workflow
CD cd.yml	Successful release	• Prepare Docker tags • Build & push to GHCR • Run Trivy security scan • Trigger Render deployment

🌿 Branch Strategy

Branch	Purpose	Release Type
main	🚀 Production	Stable releases + Deploy
develop	🧪 Development	Prereleases
deploy/ci_cd	🔧 CI/CD Testing	CI/CD prereleases

🔐 Security & Authentication

• GitHub App Token: Short-lived, scoped tokens for releases
• Least Privilege: Minimal permissions for each workflow
• Secret Management: All credentials in GitHub Secrets
• Vulnerability Scanning: Trivy scans on every image build

🛠️ Local Release Testing

# Dry run (shows next version)
./scripts/release.sh

# Publish release (requires GITHUB_TOKEN)
GITHUB_TOKEN=ghp_... ./scripts/release.sh --publish --yes

---

🗺️ Roadmap

• 🔗 Add contract tests for API endpoints
• 💬 Add CI notifications (Slack/MS Teams)
• 🔐 Implement API authentication
• 📊 Add monitoring and observability

---

🤝 Contributing

Contributions are welcome! Here's how to get started:

📝 Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Use conventional commits for semantic versioning
4. Add tests for new functionality
5. Run linting and formatting
6. Submit a pull request with clear description

🔍 Pre-commit Checklist

# Lint code
uv run ruff check app tests

# Format code
uv run ruff format app tests

# Run tests
uv run pytest -q

# Type check
uv run mypy app

💬 Commit Convention

feat: add new feature
fix: resolve bug
docs: update documentation
test: add test coverage
chore: maintenance tasks

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

👨‍💻 Author

Michael Adebayo

---

⭐ If you find this project helpful, please give it a star! ⭐