How ashishpatel26/fastapi-ci-cd works
1. Repository purpose
- This repo is primarily a FastAPI service plus delivery pipeline. The application itself is very small; most of the architecture is around how it is built, tested, containerized, published, and deployed.
2. Application runtime boundary
- main.py is the runtime entrypoint for the service.
- It exposes three HTTP endpoints:
- / for the greeting response
- /health for liveness/readiness-style checks
- /version for release identification
- This is a stateless API service with no database, queue, cache, or internal service dependencies visible in the repo.
3. Test boundary
- tests/test_main.py contains the unit/integration-style checks for the FastAPI app.
- The test suite is small and directly validates the contract of the public endpoints.
- In the architecture diagram, this is the quality gate before container build and release.
4. Dependency and build management
- pyproject.toml and uv.lock define the Python environment and pinned dependencies.
- uv is the package manager/runtime coordinator used in local development and CI.
- This matters architecturally because the repo is designed for reproducible builds rather than ad hoc dependency resolution.
5. Containerization layer
- Dockerfile packages the FastAPI app into a runnable container image.
- The README indicates Podman is the container engine used in the workflow, though the image artifact itself is standard OCI-compatible.
- This container is the handoff point between application build and cluster deployment.
6. Continuous integration flow
- .github/workflows/ci.yml runs on pushes/PRs as the validation pipeline.
- The documented sequence is:
- uv sync --frozen
- pytest
- podman build
- The CI boundary verifies both code correctness and container buildability before release.
7. Continuous delivery / release flow
- .github/workflows/cd.yml handles publishing to GHCR (ghcr.io).
- The release flow logs in with a GitHub token, builds images tagged with both commit SHA and latest, and pushes them to the registry.
- In the diagram, GHCR is the artifact registry between CI and Kubernetes.
8. Kubernetes deployment layer
- fastapi-chart/ is a Helm chart that defines the cluster-side deployment.
- The chart templates include:
- deployment.yaml for the pod workload
- service.yaml for network exposure
- values.yaml provides the configurable image/service parameters, making the deployment reusable across environments.
9. Deployment dependency chain
- Kubernetes does not build the app; it pulls the image from GHCR and runs the container created by the pipeline.
- A GHCR image pull secret is required for private registry access.
- The main runtime path is therefore:
- source code → CI tests → container image → GHCR → Helm release → Kubernetes pod/service
10. Local development and verification
- The README and supporting files (command.md, steps.md) show the intended local workflow:
- run the app with Uvicorn
- validate with tests
- build and run the container
- optionally deploy to Minikube
- This is a developer-facing path that mirrors the production pipeline but stays local.
11. Infrastructure assumptions
- The deployment target is Kubernetes, with Minikube used for local cluster testing.
- Podman is the container runtime/tooling emphasized in CI/CD.
- GHCR is the external infrastructure service used to store deployable artifacts.
- There are no other external backend services evident in the repo.
12. What to draw in an architecture diagram
- Show a small FastAPI application box with three routes.
- Add a testing gate connected to the source code.
- Add a build/publish pipeline that produces container images and pushes them to GHCR.
- Add a Kubernetes/Helm deployment that pulls from GHCR and exposes the app via a Service.
- Keep docs/assets out of the runtime path; they support the project but do not participate in execution.
Main entry points: README.md Workflow docs · fastapi-chart Helm chart · main.py Service API · ci.yml CI pipeline
Components 18
Runtime
FastAPI service entrypoint and request handling
- Service API · Runtime entrypoint exposing /, /health, and /version
main.py
Quality
Tests and reproducible Python environment
- Endpoint tests · Validates the public HTTP contract for the service
tests/test_main.py - Python deps · Declares the Python environment and project metadata
pyproject.toml - Locked deps · Pinned dependency set for reproducible installs
uv.lock
Delivery
Container build and registry publication
- CI pipeline · Runs sync, tests, and container build on PRs and pushes
.github/workflows/ci.yml - Release pipeline · Builds and pushes release images to GHCR
.github/workflows/cd.yml - Container build · Packages the FastAPI app into an OCI image
Dockerfile - Podman build · Runtime used to build the image in local and CI workflows
- GHCR · Artifact registry holding release images
Deployment
Helm chart and Kubernetes release
- Helm chart · Reusable Kubernetes deployment package
fastapi-chart - Workload · Defines the pod spec that runs the container image
fastapi-chart/templates/deployment.yaml - Service · Exposes the running pod inside the cluster
fastapi-chart/templates/service.yaml - Chart values · Configures image and service parameters for releases
fastapi-chart/values.yaml - Kubernetes · Executes the deployed container and service
Local Dev
Developer-facing workflow docs and setup
- Minikube · Local Kubernetes environment for verification
- Workflow docs · Describes local run, test, build, and deploy steps
README.md - Steps guide · Supporting process notes for the developer workflow
steps.md - Commands · Quick command reference for local development
command.md
Connections 26
- Python deps → Locked deps: pins · Project metadata and locked dependencies define the reproducible environment
- Python deps → Service API: supports · Application code runs within the declared Python environment
- Locked deps → CI pipeline: syncs · CI installs the frozen dependency set before validation
- Service API → Endpoint tests: verified by · Endpoint tests exercise the FastAPI contract
- Endpoint tests → CI pipeline: gate · Tests are the quality gate in CI
- Service API → Container build: baked into · The service source is packaged into the container image
- Container build → Podman build: built with · Podman performs the image build step
- CI pipeline → Podman build: builds · CI uses Podman to verify the image can be built
- Podman build → GHCR: pushes · Release builds are published as registry images
- Release pipeline → GHCR: publishes · CD tags and pushes images to the registry
- GHCR → Workload: pulled by · Kubernetes pulls the published image for deployment
- Chart values → Workload: configures · Values supply the image and runtime settings
- Chart values → Service: configures · Values also shape service exposure
- Helm chart → Workload: includes · The Helm chart renders the deployment template
- Helm chart → Service: includes · The Helm chart renders the service template
- Helm chart → Chart values: parameterized by · Chart defaults and overrides control the release
- Workload → Kubernetes: runs on · Deployment manifests create pods in the cluster
- Service → Kubernetes: exposes · Service manifests route traffic to the workload
- Minikube → Kubernetes: local target · Minikube is the local cluster used for verification
- Workflow docs → Service API: documents · README explains how to run the service locally
- Workflow docs → Endpoint tests: documents · README covers the validation workflow
- Workflow docs → CI pipeline: documents · README summarizes CI behavior
- Workflow docs → Release pipeline: documents · README summarizes release behavior
- Workflow docs → Helm chart: documents · README explains Kubernetes deployment
- Steps guide → Workflow docs: supports · Supporting notes expand the documented workflow
- Commands → Workflow docs: supports · Command reference complements the main workflow docs