A learning repository for modern CI/CD practices
This is a learning repository that walks you through a clean, real-world CI/CD flow using a tiny Python calculator.
Simple Version (ELI5): Think of it like a school project with a smart checklist:
- Developer Flow: You make changes on your computer and run the calculator/tests.
- Pre-commit Hooks: A friendly gatekeeper checks your work before it gets saved.
- PR Review + CI Workflows: A robot team re-checks everything in GitHub before merge.
- Internal CI Tweaks: Extra speed + reporting tricks make the robot team fast and helpful.
Technical Version (for developers):
| Stage | What Happens | Tools Used |
|---|---|---|
| Developer flow | Local dev + tests before push | Python + pytest |
| Pre-commit hooks | Security + linting + formatting | pre-commit + Ruff + Gitleaks |
| PR review & CI workflows | Parallel/sequential jobs, coverage & security gates | GitHub Actions + Codecov + CodeQL + Bandit |
| Internal CI tweaks | Caching + report history + artifacts | Actions cache + Allure + GitHub Pages |
Live Demo: Test Reports on GitHub Pages
- What is This?
- The 4-Stage Learning Path
- 📚 Start Learning
- Quick Start
- Project Structure
- Documentation
- 🛠️ Awesome GitHub Tools
- Contributing
An instructional repository that teaches professional CI/CD through hands-on practice with a simple Python calculator.
✅ Python project structure and testing ✅ Pre-commit hooks for code quality ✅ GitHub Actions CI/CD pipelines ✅ Enterprise features (Allure, caching, quality gates)
Perfect for: Students, bootcamp grads, developers learning DevOps.
This repository teaches CI/CD in 4 progressive stages:
1. Developer Flow
→ Write code locally, run tests
2. Pre-commit Hooks
→ Automatic quality checks before commits
3. CI/CD Workflows
→ Automated testing in the cloud
4. Advanced Features
→ Enterprise reporting, caching, quality gates
Total learning time: ~70 minutes
Follow the step-by-step guides in order:
| # | Guide | Time |
|---|---|---|
| 1 | Getting Started | 5 min |
| 2 | Understanding the Code | 10 min |
| 3 | Running Tests | 10 min |
| # | Guide | Time |
|---|---|---|
| 4 | Pre-commit Hooks | 10 min |
| # | Guide | Time |
|---|---|---|
| 5 | CI/CD Basics | 15 min |
| # | Guide | Time |
|---|---|---|
| 6 | Advanced Features | 20 min |
👉 Begin with Guide 1: Getting Started
For those who want to jump right in:
Option A: Using pip (traditional)
# Install dependencies
pip install -r requirements.txt
# Run calculator
python -m src.calculator
# Run tests
pytestOption B: Using uv (modern & fast) ⚡
# Install dependencies (creates venv automatically)
uv sync --dev
# Run calculator
uv run python -m src.calculator
# Run tests
uv run pytestOption A: Using pip
pip install pre-commit
pre-commit installOption B: Using uv
uv sync --dev # Includes pre-commit
pre-commit installpytest --alluredir=allure-results
allure serve allure-resultsThis is a learning repository! Here are key insights about CI/CD concepts demonstrated in this project.
This project demonstrates a sophisticated 8-job pipeline with parallel and sequential stages:
┌──────────────────────────────────────────────────────┐
│ STAGE 1: PARALLEL │
│ (all three jobs start simultaneously) │
└──────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────┐ ┌──────────┐ ┌─────────────┐
│ 🔍 Lint │ │🔒Security│ │🧪 Unit Tests│
└────┬────┘ └────┬─────┘ └──────┬──────┘
│ │ │
└──────────────┼─────────────────┘
▼
┌──────────────────────────────────────────────────────┐
│ STAGE 2: DOCKER │
│ (only runs if Dockerfile/src/requirements changed) │
└──────────────────────────────────────────────────────┘
│
▼
┌───────────────┐
│🔎 Check Changes│
└───────┬───────┘
│
▼
┌───────────────┐
│🐳 Docker Build│
└───────┬───────┘
│
▼
┌───────────────┐
│💨 Smoke Test │
└───────┬───────┘
│
▼
┌──────────────────────────────────────────────────────┐
│ STAGE 3: REPORT & DEPLOY │
└──────────────────────────────────────────────────────┘
│
▼
┌──────────┐
│📊 Report │
└────┬─────┘
│
▼
┌──────────┐
│🚀 Deploy │
└──────────┘
Tool Focus Why It Matters Codecov Code quality "Are you testing enough?" - tracks coverage trends CodeQL Security "Is your code safe?" - finds vulnerabilities automatically Together they form a quality + security gate that catches both coverage regressions and vulnerabilities before merge.
# These lines are excluded from coverage (standard practice): if __name__ == "__main__": main()Why?
- Interactive CLI code (
input(),print()) is meant for human interaction, not unit tests- Testing these requires mocking stdin/stdout - low value, high complexity
- The core logic (Calculator class) is what matters - and that's at 100%
- This is standard practice in Python projects (Django, Flask, etc.)
Custom instructions in
.github/copilot-instructions.mdtell Copilot what's important for YOUR project:
- Without context: Copilot reviews can be noisy with false positives
- With instructions: Focused reviews on what actually matters
- Think of it as: Giving a human reviewer onboarding docs
Concept How It Works Parallel jobs Jobs without needs:start immediately togetherSequential jobs Jobs with needs: [job1, job2]wait for ALL listed jobsRunners Each parallel job gets its own fresh VM Total time max(parallel jobs) + sequential jobsExample from this repo:
# These run in PARALLEL (no needs:) lint: runs-on: ubuntu-latest security: runs-on: ubuntu-latest # This waits for BOTH to complete test: needs: [lint, security] # Won't start until both finish
Cache What It Stores Invalidates When pip cache Downloaded Python packages requirements.txtchangespytest cache Test collection data Test files change Result: First run ~45s, subsequent runs ~15s (3x faster!)
simple-calculator/
├── guides/ # 📖 Step-by-step learning (START HERE!)
├── src/ # 🧠 Calculator code
├── tests/ # ✅ Test code
├── docs/ # 📚 Deep-dive documentation
│ └── assets/ # 🎨 Images
├── .github/workflows/ # 🤖 CI/CD automation
└── prompts/ # 🧩 Copy-paste CI/CD prompts
See docs/reference/STRUCTURE.md for details.
- 📖 Learning Guides - Progressive 6-guide learning path (~70 min)
- 🏗️ ARCHITECTURE.md - Complete system overview
- 🚀 CI-CD.md - CI/CD insights & best practices
- 📊 ALLURE.md - Enterprise test reporting
- 🌐 GITHUB-PAGES.md - Free hosting setup
- 🧪 TESTING.md - pytest testing guide
- ⚡ UV.md - Fast package manager
- 🔧 TROUBLESHOOTING.md - Common issues
- 🧩 Prompts - Copy-paste CI/CD setup for your repos
- 🤖 Copilot Spaces - Interactive AI-powered exploration of this repository (requires Copilot licensing)
- 💬 GitMCP Chat - Chat with this repository using GitMCP
Enhance your GitHub workflow with these helpful tools:
-
📱 GitHub Mobile App - Official GitHub app for iOS and Android. Manage repositories, review code, and respond to issues on the go.
-
🎨 GitHub Material Design Chrome Extension - Apply Material Design styling to GitHub's interface for a modern, polished look.
-
⚡ Refined GitHub - Browser extension that simplifies the GitHub interface and adds 200+ useful features including linkified references, reaction avatars, merge conflict fixers, and more. Available for Chrome and Firefox.
-
🤖 GitHub MCP - Model Context Protocol server for GitHub integration, enabling AI assistants to interact with GitHub repositories, issues, and pull requests through the MCP framework.
- Fork the repository
- Create a feature branch
- Make your changes
- Run
pytestandpre-commit run --all-files - Submit a pull request
CI will automatically test your changes.
This project is for educational purposes.
👉 Start with Guide 1: Getting Started
Learn professional CI/CD practices through hands-on experience!