{"id":23857532,"url":"https://github.com/gsinghjay/fast-api-ci-cd","last_synced_at":"2026-02-08T23:37:58.820Z","repository":{"id":270535383,"uuid":"910679868","full_name":"gsinghjay/fast-api-ci-cd","owner":"gsinghjay","description":"FastAPI Full Stack with CI Template (Working Version: v6.3.0)","archived":false,"fork":false,"pushed_at":"2025-01-03T16:53:17.000Z","size":618,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-15T04:07:48.935Z","etag":null,"topics":["ci","commitlint","fastapi","flake8","github-actions","keep-a-changelog","poetry","python","python-semantic-release","semantic-release","semver","sqlalchemy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gsinghjay.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-01T03:33:02.000Z","updated_at":"2025-05-02T19:50:29.000Z","dependencies_parsed_at":"2025-06-15T04:07:56.172Z","dependency_job_id":"9c8de33d-904d-473e-8f55-69f033534f73","html_url":"https://github.com/gsinghjay/fast-api-ci-cd","commit_stats":null,"previous_names":["gsinghjay/fast-api-ci-cd"],"tags_count":45,"template":true,"template_full_name":null,"purl":"pkg:github/gsinghjay/fast-api-ci-cd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gsinghjay%2Ffast-api-ci-cd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gsinghjay%2Ffast-api-ci-cd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gsinghjay%2Ffast-api-ci-cd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gsinghjay%2Ffast-api-ci-cd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gsinghjay","download_url":"https://codeload.github.com/gsinghjay/fast-api-ci-cd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gsinghjay%2Ffast-api-ci-cd/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269356344,"owners_count":24403506,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-08T02:00:09.200Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ci","commitlint","fastapi","flake8","github-actions","keep-a-changelog","poetry","python","python-semantic-release","semantic-release","semver","sqlalchemy"],"created_at":"2025-01-03T02:57:19.204Z","updated_at":"2026-02-08T23:37:53.096Z","avatar_url":"https://github.com/gsinghjay.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FastAPI CI/CD Template\n\n[![CI/CD Pipeline](https://github.com/gsinghjay/fast-api-ci-cd/actions/workflows/ci.yml/badge.svg)](https://github.com/gsinghjay/fast-api-ci-cd/actions/workflows/ci.yml)\n[![Latest Release](https://img.shields.io/github/v/release/gsinghjay/fast-api-ci-cd)](https://github.com/gsinghjay/fast-api-ci-cd/releases)\n[![Python Version](https://img.shields.io/badge/python-3.11-blue)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA production-ready FastAPI template with robust CI/CD pipeline, semantic versioning, and best practices.\n\n## 📑 Features\n\n- FastAPI-based RESTful API with:\n  - QR code generation\n  - User registration with email validation\n  - Secure password hashing using bcrypt\n  - SQLite database (configurable for production)\n- Poetry for dependency management\n- Comprehensive CI/CD pipeline with GitHub Actions\n  - Optimized caching strategy for dependencies\n    - In-project Poetry virtual environments\n    - Poetry package cache\n    - Pip cache for Poetry installation\n  - Matrix testing with Python 3.11\n  - Automated dependency updates\n- Robust code quality checks\n  - Black for code formatting\n  - Flake8 with advanced plugins:\n    - flake8-docstrings for docstring validation\n    - flake8-bugbear for bug detection\n    - flake8-comprehensions for optimization\n    - flake8-simplify for code simplification\n  - MyPy for static type checking\n  - Commitlint for commit message validation\n  - Pre-commit hooks for automated validation\n- Semantic versioning with automated releases\n- Automated changelog generation on main branch\n- Structured logging with structlog\n- Prometheus metrics integration\n- Conventional Commits standard\n- Pull Request based workflow\n- Release automation on main branch\n\n## 🔄 Workflow Guide\n\n### Development Workflow\n\n1. **Create a Feature Branch**\n   ```bash\n   git checkout -b feature/your-feature  # or fix/your-fix\n   ```\n\n2. **Make Changes and Commit**\n   ```bash\n   # Stage changes\n   git add .\n\n   # Commit with conventional commit message\n   git commit -m \"feat(scope): add amazing feature\"\n   # or\n   git commit -m \"fix(scope): resolve specific issue\"\n   ```\n\n3. **Create Pull Request**\n   ```bash\n   git push origin feature/your-feature\n   # Create PR to main branch via GitHub UI\n   ```\n\n4. **Release Process**\n   - Merging to main branch automatically:\n     - Updates CHANGELOG.md\n     - Creates a new release\n     - Updates version numbers\n     - Creates GitHub release with assets\n\n### Commit Message Format\n\nFollow the Angular Commit Message Convention:\n\n```bash\n\u003ctype\u003e(\u003cscope\u003e): \u003cdescription\u003e\n\n[optional body]\n\n[optional footer]\n```\n\nTypes:\n- feat: A new feature (MINOR version bump)\n- fix: A bug fix (PATCH version bump)\n- docs: Documentation only changes\n- style: Changes that do not affect the meaning of the code\n- refactor: A code change that neither fixes a bug nor adds a feature\n- perf: A code change that improves performance\n- test: Adding missing tests or correcting existing tests\n- build: Changes that affect the build system or external dependencies\n- ci: Changes to our CI configuration files and scripts\n- chore: Other changes that don't modify src or test files\n\nBreaking Changes:\n- Add `BREAKING CHANGE:` in the footer\n- Or append `!` after type/scope (e.g., `feat!:` or `feat(api)!:`)\n- Triggers a MAJOR version bump\n\nExamples:\n```bash\n# Feature with scope\nfeat(auth): add OAuth2 authentication\n\n# Bug fix with breaking change\nfix!: remove deprecated API endpoints\n\nBREAKING CHANGE: The /v1/api/* endpoints have been removed.\n\n# Documentation update\ndocs(readme): update installation instructions\n\n# Multiple-line description with scope\nfeat(api): improve error handling for REST endpoints\n\nImplement better error messages and status codes\nfor all REST API endpoints.\n\nCloses #123\n```\n\nScope:\n- Optional parentheses-enclosed identifier\n- Indicates section of codebase (e.g., api, auth, core)\n- Should be noun describing the section\n\nDescription:\n- Imperative, present tense: \"change\" not \"changed\" nor \"changes\"\n- Don't capitalize first letter\n- No period (.) at the end\n\nBody:\n- Free-form\n- Provide context and motivation for changes\n- Use imperative, present tense\n\nFooter:\n- Reference issues being closed\n- Note breaking changes\n- Multiple footers allowed\n- Format: `token: value` or `BREAKING CHANGE: description`\n\n## 🛠️ Development Setup\n\n1. **Install Dependencies**\n   ```bash\n   # Install Poetry\n   curl -sSL https://install.python-poetry.org | python3 -\n\n   # Install project dependencies\n   poetry install\n\n   # Install commitlint\n   npm install -g @commitlint/cli @commitlint/config-conventional\n   ```\n\n2. **Set up Pre-commit Hooks**\n   ```bash\n   poetry run pre-commit install\n   poetry run pre-commit install --hook-type commit-msg\n   ```\n\n3. **Configure GitHub Token**\n   ```bash\n   # Add to your environment\n   export GH_TOKEN=your_github_pat_token\n   ```\n\n## 🚀 Running the Application\n\n```bash\n# Development server\npoetry run uvicorn app.main:app --reload --log-level debug\n\n# Production server\npoetry run uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4\n```\n\n## 📝 API Documentation\n\n### User Registration\n```bash\ncurl -X POST \"http://localhost:8000/api/v1/users/register\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"email\": \"user@example.com\",\n       \"password\": \"StrongPass123!\",\n       \"full_name\": \"John Doe\"\n     }'\n```\n\nPassword requirements:\n- Minimum 8 characters\n- At least one uppercase letter\n- At least one lowercase letter\n- At least one number\n- At least one special character\n\nResponse (201 Created):\n```json\n{\n  \"id\": 1,\n  \"email\": \"user@example.com\",\n  \"full_name\": \"John Doe\"\n}\n```\n\n### Generate QR Code\n```bash\ncurl -X POST \"http://localhost:8000/api/v1/qr-code/generate\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"url\": \"https://example.com\",\n       \"fill_color\": \"#000000\",\n       \"background_color\": \"#FFFFFF\",\n       \"box_size\": 10,\n       \"border\": 4\n     }'\n```\n\n## 🔍 Environment Variables\n\nRequired environment variables:\n- `GH_TOKEN`: GitHub token for releases\n- `LOG_LEVEL`: Logging level (debug/info/warning/error)\n- `PORT`: Application port (default: 8000)\n- `WORKERS`: Number of worker processes (default: 1)\n- `METRICS_ENABLED`: Enable/disable Prometheus metrics\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create your feature branch\n3. Make changes following our commit conventions\n4. Create a Pull Request to main branch\n5. Ensure CI checks pass\n6. Wait for review and merge\n\n## 📚 Documentation\n\nFor more detailed documentation, see:\n- [CHANGELOG.md](CHANGELOG.md) for version history\n- [API Documentation](http://localhost:8000/docs) when running locally\n- [GitHub Actions Workflows](.github/workflows) for CI/CD details\n\n## 🔧 Setup Instructions\n\n### Using This Template\n\n1. **Create New Repository**\n   - Click \"Use this template\" on GitHub\n   - Or clone and reinitialize:\n     ```bash\n     git clone https://github.com/gsinghjay/fast-api-ci-cd\n     cd fast-api-ci-cd\n     rm -rf .git\n     git init\n     ```\n\n2. **Configure GitHub Repository**\n   - Go to repository Settings → Branches → Add rule\n   - Protect `main` branch\n   - Require pull request reviews\n   - Require status checks to pass\n   - Note: The workflows use `GITHUB_TOKEN` which is automatically provided by GitHub Actions\n\n3. **Update Configuration Files**\n   - Update `pyproject.toml`:\n     ```toml\n     [tool.poetry]\n     name = \"your-project-name\"\n     version = \"1.0.0\"\n     authors = [\"Your Name \u003cyour.email@example.com\u003e\"]\n     ```\n   - Update GitHub workflow files in `.github/workflows/`\n   - Update repository URLs in documentation\n\n### Workflow Debugging Commands\n\n```bash\n# List recent workflow runs\ngh run list --limit 5\n\n# Watch a specific workflow run\ngh run watch\n\n# View workflow run details\ngh run view --log\n\n# List failed workflow runs\ngh run list --status failed\n\n# Download workflow artifacts\ngh run download \u003crun-id\u003e\n\n# View workflow in browser\ngh run view --web\n```\n\n### Common Issues \u0026 Solutions\n\n1. **Release Creation Fails**\n   - Check workflow permissions in repository settings\n   - Ensure commit messages follow convention\n   - Verify branch protection settings\n   - Check git configuration:\n     ```bash\n     git config --list\n     gh auth status\n     ```\n\n2. **Changelog Not Updating**\n   - Only updates on main branch merges\n   - Verify commit message format\n   - Check workflow logs for errors\n   - Ensure workflow has write permissions\n\n3. **Pre-commit Hooks Failing**\n   - Update hooks:\n     ```bash\n     pre-commit clean\n     pre-commit autoupdate\n     ```\n   - Check commit message format\n   - Run black manually:\n     ```bash\n     poetry run black .\n     ```\n\n4. **Workflow Permission Issues**\n   - Repository Settings → Actions → General\n   - Enable \"Allow GitHub Actions to create and approve pull requests\"\n   - Check workflow permissions in yml files\n   - Ensure proper permissions are set in workflow files\n\n## 🔄 Semantic Versioning\n\nThis project follows [Semantic Versioning 2.0.0](https://semver.org/) principles. Version numbers are structured as MAJOR.MINOR.PATCH:\n\n1. **MAJOR** version - Incremented for incompatible API changes\n2. **MINOR** version - Incremented for backward-compatible new functionality\n3. **PATCH** version - Incremented for backward-compatible bug fixes\n\nAdditional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.\n\n### Version Bumping Rules\n\n- Breaking changes (MAJOR): `BREAKING CHANGE:` in commit footer or `!` after type/scope\n- New features (MINOR): `feat:` commit type\n- Bug fixes (PATCH): `fix:` commit type\n- No version bump: `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`\n\n## 🚀 Python Semantic Release\n\nWe use [Python Semantic Release](https://python-semantic-release.readthedocs.io/en/latest/) for automated versioning and changelog generation. Key features:\n\n- Automatic version bumping based on commit messages\n- Changelog generation following Keep a Changelog format\n- GitHub release creation and asset publishing\n- Support for pre-releases and build metadata\n\n### Configuration\n\nConfiguration in `pyproject.toml` integrates our versioning and changelog standards:\n\n```toml\n[tool.python_semantic_release]\n# Version Management\nversion_variables = [\"app/__init__.py:__version__\"]  # Update version in code\nversion_toml = [\"pyproject.toml:tool.poetry.version\"]  # Update version in pyproject.toml\nversion_source = [\"tag\", \"commit\"]  # Determine version from tags and commits\nmajor_on_zero = false  # Follow SemVer for 0.x versions\ntag_format = \"v{version}\"  # Git tag format (e.g., v1.0.0)\n\n# Commit Parsing\ncommit_parser = \"conventional_commits\"  # Use Conventional Commits standard\ncommit_author = \"github-actions[bot] \u003c41898282+github-actions[bot]@users.noreply.github.com\u003e\"\n\n# Changelog Management\nchangelog_file = \"CHANGELOG.md\"  # Keep a Changelog file\nchangelog_sections = [  # Keep a Changelog categories\n    \"feature\",    # Maps to Added\n    \"fix\",        # Maps to Fixed\n    \"breaking\",   # Maps to Changed with breaking changes\n    \"documentation\",\n    \"performance\",\n    \"refactor\"\n]\n\n# Release Settings\nupload_to_repository = false\nbuild_command = \"poetry build\"\ntag_type = \"annotated\"  # Use annotated tags for better documentation\n```\n\n### Automatic Standards Compliance\n\n1. **Semantic Versioning**:\n   - Analyzes commit messages using Conventional Commits\n   - Automatically determines version bumps:\n     - `BREAKING CHANGE` → MAJOR\n     - `feat:` → MINOR\n     - `fix:` → PATCH\n   - Creates appropriate Git tags\n\n2. **Keep a Changelog**:\n   - Maintains CHANGELOG.md in the standard format\n   - Groups changes by type (Added, Changed, Fixed, etc.)\n   - Includes release dates and version links\n   - Keeps an Unreleased section for upcoming changes\n   - Links to Git comparisons between versions\n\n### Manual Release Commands\n\n```bash\n# Check what the next version would be\npoetry run semantic-release version --noop\n\n# Create a new version (local only)\npoetry run semantic-release version\n\n# Create and publish a new release\npoetry run semantic-release publish\n```\n\n### Environment Setup\n\nRequired environment variables:\n- `GH_TOKEN`: GitHub Personal Access Token with `repo` scope\n- For fine-grained tokens: `contents` permission required\n\n## 🔄 Changelog Guidelines\n\nWe follow the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) principles for maintaining our CHANGELOG.md. This ensures our changelog is:\n\n### Guiding Principles\n\n- Written for humans, not machines\n- Easy to link to any section\n- One sub-section per version\n- List releases in reverse-chronological order\n- Include release date for each version\n- Group changes by type\n- Mention whether we follow Semantic Versioning\n\n### Types of Changes\n\n- `Added` - New features\n- `Changed` - Changes in existing functionality\n- `Deprecated` - Soon-to-be removed features\n- `Removed` - Now removed features\n- `Fixed` - Any bug fixes\n- `Security` - In case of vulnerabilities\n\n### Good Practices\n\n- Keep an `Unreleased` section at the top for tracking upcoming changes\n- Never use commit log diffs as changelog entries\n- Always write clear, human-friendly descriptions\n- Use ISO 8601 format for dates (YYYY-MM-DD)\n- Make it clear when breaking changes occur\n- Keep entries consistent and well-organized\n- Link to issues, PRs, and other relevant information\n\n### Example Entry\n\n```markdown\n## [1.0.0] - 2024-01-02\n\n### Added\n- New API endpoint for QR code generation\n- Support for custom QR code colors\n\n### Changed\n- Improved error handling in API responses\n- Updated dependencies to latest versions\n\n### Fixed\n- Issue with QR code size calculation\n- Memory leak in image processing\n\n[1.0.0]: https://github.com/username/project/compare/v0.9.0...v1.0.0\n```\n\n## 🔄 Workflow Architecture\n\n```mermaid\nflowchart TD\n    subgraph \"CI/CD Pipeline\"\n        A[Push/PR] --\u003e B{Event Type?}\n\n        B --\u003e |PR/Push| C[Setup Python]\n        C --\u003e D[Install Dependencies]\n        D --\u003e E[Cache Environment]\n\n        E --\u003e F[Lint Check]\n        E --\u003e G[Test]\n\n        F \u0026 G --\u003e H{All Checks Pass?}\n\n        H --\u003e|No| I[Report Failure]\n        H --\u003e|Yes \u0026 PR| J[Ready for Review]\n        H --\u003e|Yes \u0026 Push to Main| K[Semantic Release]\n\n        K --\u003e L[Generate Changelog]\n        L --\u003e M[Create Release]\n        M --\u003e N[Publish Assets]\n\n        subgraph \"Skip Release Conditions\"\n            S1[Skip if]\n            S2[Commit by github-actions]\n            S3[\"Message contains 'skip ci'\"]\n            S4[\"Message has 'chore(release)'\"]\n            S1 --\u003e S2 \u0026 S3 \u0026 S4\n        end\n    end\n\n    classDef trigger fill:#90EE90\n    classDef setup fill:#FFE4B5\n    classDef check fill:#FFB6C1\n    classDef release fill:#ADD8E6\n    classDef skip fill:#D3D3D3\n\n    class A trigger\n    class C,D,E setup\n    class F,G,H check\n    class K,L,M,N release\n    class S1,S2,S3,S4 skip\n```\n\n### Workflow Files Structure\n\n1. **CI Workflow** (.github/workflows/ci.yml)\n   - Main orchestrator workflow\n   - Triggers on push to main and pull requests\n   - Controls the release process\n   - Uses reusable workflows for setup, lint, and test\n\n2. **Setup Workflow** (.github/workflows/setup-python.yml)\n   - Sets up Python environment\n   - Installs and configures Poetry\n   - Creates and caches virtual environment\n   - Shares environment via artifacts\n\n3. **Lint Workflow** (.github/workflows/lint.yml)\n   - Runs Black code formatter\n   - Validates commit messages with Commitlint\n   - Uses shared virtual environment\n\n4. **Test Workflow** (.github/workflows/test.yml)\n   - Runs pytest with coverage\n   - Uses shared virtual environment\n   - Reports test results\n\n### Workflow Execution\n\n1. **Setup Phase:**\n   - Initializes Python 3.11 environment\n   - Installs Poetry and dependencies\n   - Creates virtual environment\n   - Caches dependencies for speed\n   - Shares environment via artifacts\n\n2. **Parallel Checks:**\n   - Lint and Test jobs run concurrently\n   - Both use the shared virtual environment\n   - All checks must pass to proceed\n\n3. **Release Phase (Main Branch Only):**\n   - Triggered on push to main\n   - Uses python-semantic-release\n   - Updates CHANGELOG.md\n   - Creates GitHub release\n   - Publishes release assets\n\n### Skip Conditions\n\nWorkflow skips release when:\n- Commit is from github-actions[bot]\n- Commit message contains:\n  - [skip ci]\n  - chore(release)\n- Event is a pull request\n\n### Security and Permissions\n\n- Uses built-in GITHUB_TOKEN\n- Minimal required permissions per job:\n  - Lint: read (contents, pull-requests)\n  - Test: read (contents), write (checks)\n  - Release: write (contents, id-token)\n\n### Environment Optimization\n\n- Shared virtual environment via artifacts\n- Poetry for dependency management\n- Cached dependencies:\n  - Poetry virtual environment\n  - Pip cache\n  - Poetry package cache\n- Preserved environment across jobs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgsinghjay%2Ffast-api-ci-cd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgsinghjay%2Ffast-api-ci-cd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgsinghjay%2Ffast-api-ci-cd/lists"}