FastAPI CI/CD with GitHub Actions (Lint, Test & Ship Automatically)

Prerequisites: a FastAPI app with tests (fastapi-unit-testing, fastapi-integration-testing) and a Dockerfile (fastapi-docker). This post wires them into an automated pipeline.

fastapi-ci/
├── .github/
│   └── workflows/
│       └── ci.yml            # the pipeline (lint → test → build)
├── app/                      # your FastAPI app
├── tests/                    # pytest suite
├── Dockerfile
└── requirements.txt

1The Problem: "Works on My Machine" (See It First)

Without CI, the only thing standing between a bug and main is whether the author remembered to run the tests locally — with their local Python, their local env vars, their local database.

Dev A:  forgets to run pytest, pushes to main   ──►  broken tests merged
Dev B:  pulls main, nothing runs                ──►  "why is prod 500-ing?"
Dev C:  "but it works on my machine..."         ──►  different Python version

No gate. No clean-room check. Bugs merge because a human forgot a step.

2GitHub Actions 101

A pipeline is just a YAML file in .github/workflows/. Four concepts and you can read any workflow:

3Your First Workflow: Lint + Test

Create .github/workflows/ci.yml. This runs on every push to main and every pull request: check out the code, set up Python (with pip caching baked in), install, lint, and test.

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: pip                 # built-in pip dependency caching

      - run: pip install -r requirements.txt

      - name: Lint
        run: ruff check .

      - name: Test
        run: pytest -v

4Testing Against a Real Postgres (Service Container)

Your integration tests need a database. GitHub Actions can spin up a service container — a Postgres that lives for the duration of the job. The key detail everyone misses: a health-check so your tests don't start before Postgres is ready.

jobs:
  test:
    runs-on: ubuntu-latest

    services:
      db:
        image: postgres:16
        env:
          POSTGRES_USER: app
          POSTGRES_PASSWORD: app
          POSTGRES_DB: app_test
        ports:
          - 5432:5432
        # wait until Postgres is actually accepting connections
        options: >-
          --health-cmd "pg_isready -U app"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    env:
      # your app/tests read the DB URL from the environment
      DATABASE_URL: postgresql+psycopg://app:app@localhost:5432/app_test

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: pip
      - run: pip install -r requirements.txt
      - run: pytest -v

5Caching Dependencies (Faster Runs)

cache: pip covers most projects. If you need finer control (e.g. caching a custom directory or a tool's cache), use actions/cache directly with a key derived from your lockfile:

      - uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          # new key when requirements change -> fresh install; else cache hit
          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
          restore-keys: |
            ${{ runner.os }}-pip-

6Build & Push a Docker Image to GHCR

Green tests are step one. Now the CD half: on merge to main, build your Docker image and push it to the GitHub Container Registry (GHCR). This job needs: test, so it only runs if tests passed, and is gated to the main branch.

  docker:
    needs: test                                   # only if tests pass
    if: github.ref == 'refs/heads/main'           # only on main, not PRs
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write                             # required to push to GHCR
    steps:
      - uses: actions/checkout@v4

      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}    # auto-provided, no setup

      - uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: |
            ghcr.io/${{ github.repository }}:latest
            ghcr.io/${{ github.repository }}:${{ github.sha }}

7Adding a Deploy Step (CD)

The last mile depends on your host. Most platforms expose a deploy hook or CLI — call it after the image is pushed, feeding any credentials in from encrypted repository secrets (never hardcoded).

      - name: Trigger deploy
        run: curl -fsS -X POST "$DEPLOY_HOOK"
        env:
          DEPLOY_HOOK: ${{ secrets.DEPLOY_HOOK }}   # set in repo Settings → Secrets

8Try It (Push & Watch)

git add .github/workflows/ci.yml
git commit -m "ci: lint, test, and build"
git push origin main

GitHub → your repo → Actions tab:

CI  #12  ✓ main
├── test    ✓  (ruff clean, 6 passed in 0.9s, Postgres service healthy)
└── docker  ✓  (pushed ghcr.io/you/app:latest + :a1b2c3d)

green check ✓ appears next to your commit — safe to merge

![CI](https://github.com/USERNAME/REPO/actions/workflows/ci.yml/badge.svg)

9Common Mistakes (and Fixes)

10Production Notes

• Turn on branch protection. Settings → Branches → require the CI check to pass before merging to main. A green pipeline only helps if red actually blocks the merge.
• Run migrations in CI. Apply your Alembic migrations against the service DB before pytest (fastapi-alembic-migrations) so you test the real schema, not just your models.
• Matrix-test when it matters. A strategy.matrix over Python versions catches version-specific breakage — worth it for libraries, overkill for a single-deploy app.
• Deploy on tags for releases. Trigger CD on version tags (on: push: tags: ['v*']) so you ship deliberate releases, not every commit to main.

11What's Next

Recap: a workflow in .github/workflows/ lints and tests every push on a clean runner — against a real Postgres service container — and, on main, builds and pushes a Docker image to GHCR. Pin your actions, keep secrets in repository secrets, and require the check with branch protection. Ship with confidence, not crossed fingers.

fastapi-ci/                          # ✅ finished
├── .github/
│   └── workflows/
│       └── ci.yml            # test (ruff + pytest + Postgres) → docker (GHCR)
├── app/
├── tests/
├── Dockerfile
└── requirements.txt