CI/CD for FastAPI with GitHub Actions

By Khimananda Oli | Last reviewed: August 2026

Shipping Python APIs without automated validation is a liability, especially when handling sensitive data or high-traffic endpoints. Implementing CI/CD for FastAPI with GitHub Actions solves this by enforcing type safety, running async tests against real dependencies, and deploying via secure OIDC authentication rather than long-lived credentials. This guide provides the exact workflow configuration, testing strategies, and infrastructure patterns I use in production to keep FastAPI services reliable and audit-ready.

How do you structure a GitHub Actions workflow for FastAPI?

A production-grade workflow must separate concerns into distinct jobs that fail fast and provide clear feedback. For CI/CD for FastAPI with GitHub Actions, I recommend a matrix strategy that validates against multiple Python versions while keeping the main branch protected. The key is using modern tooling like uv for dependency resolution, which is significantly faster than pip in CI environments.

Core workflow configuration

Your workflow file at .github/workflows/fastapi-ci.yml should define explicit triggers and concurrency groups to prevent redundant runs. Always pin action versions to SHA hashes for supply chain security, especially in regulated environments where audit trails matter.

name: FastAPI CI/CD Pipeline
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.11", "3.12"]
    services:
      postgres:
        image: postgres:16-alpine
        env:
          POSTGRES_DB: testdb
          POSTGRES_PASSWORD: testpass
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v4
      - name: Install uv
        uses: astral-sh/setup-uv@v3
      - name: Set up Python ${{ matrix.python-version }}
        run: uv python install ${{ matrix.python-version }}
      - name: Install dependencies
        run: uv sync --frozen
      - name: Run linting
        run: uv run ruff check .
      - name: Run type checking
        run: uv run mypy app/
      - name: Run async tests
        env:
          DATABASE_URL: postgresql://postgres:testpass@localhost:5432/testdb
        run: uv run pytest --cov=app --cov-report=xml -n auto

This configuration leverages GitHub-hosted service containers for integration testing, eliminating the need for external test databases. If your team requires deeper insight into test reliability, consider reading about integration testing in CI pipelines to understand coverage gates and flaky test detection.

How do you test FastAPI applications with async dependencies in CI?

FastAPI’s async nature requires special handling in CI. Standard pytest won’t properly exercise async endpoints or database sessions without additional configuration. You need pytest-asyncio with explicit event loop management and proper fixture scoping to avoid connection leaks during parallel test execution.

Configuring async test fixtures

Create a conftest.py that manages the async session lifecycle. This pattern ensures each test gets an isolated transaction that rolls back automatically, preventing state leakage between tests—a common source of flaky CI failures.

# tests/conftest.py
import pytest_asyncio
from httpx import AsyncClient, ASGITransport
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from app.main import app
from app.database import get_async_session

@pytest_asyncio.fixture
async def async_client():
    transport = ASGITransport(app=app)
    async with AsyncClient(transport=transport, base_url="http://test") as client:
        yield client

@pytest_asyncio.fixture
async def db_session():
    engine = create_async_engine(
        os.environ["DATABASE_URL"].replace("postgresql://", "postgresql+asyncpg://"),
        pool_pre_ping=True
    )
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)
    async with AsyncSession(engine) as session:
        yield session
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.drop_all)
    await engine.dispose()

For observability during test runs, integrate OpenTelemetry tracing even in CI. This helps diagnose performance regressions before they reach production. See instrumenting apps with OpenTelemetry for implementation details that work seamlessly in test environments.

How do you optimize Docker builds for FastAPI in GitHub Actions?

Docker layer caching is critical for keeping CI feedback loops under five minutes. Without proper cache configuration, every push rebuilds all dependencies from scratch. Use BuildKit with GitHub Actions cache backend and multi-stage builds to minimize image size and build time.

Multi-stage Dockerfile with uv

This Dockerfile separates build dependencies from runtime, producing a slim final image. The uv export command generates a requirements.txt compatible with pip for the final stage, avoiding bundling the uv binary in production.

# Dockerfile
FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS builder
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-install-project --no-dev
COPY . .
RUN uv build --wheel

FROM python:3.12-slim-bookworm AS runtime
WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
COPY --from=builder /app/.venv /app/.venv
COPY --from=builder /app/dist/*.whl /tmp/
RUN pip install --no-cache-dir /tmp/*.whl && rm -rf /tmp/*
USER nonroot:nonroot
EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

GitHub Actions Docker build with caching

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3
- name: Login to Container Registry
  uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}
- name: Build and push Docker image
  uses: docker/build-push-action@v6
  with:
    context: .
    push: ${{ github.event_name != 'pull_request' }}
    tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
    cache-from: type=gha
    cache-to: type=gha,mode=max
    platforms: linux/amd64,linux/arm64

For teams managing multiple environments, understanding managing multiple environments in IaC ensures your Docker tagging strategy aligns with staging and production promotion workflows.

How do you deploy FastAPI securely using OIDC in GitHub Actions?

Static AWS access keys in GitHub Secrets are a security anti-pattern. They rotate poorly, lack audit trails, and violate least-privilege principles. OpenID Connect (OIDC) federation allows GitHub Actions to assume IAM roles temporarily, providing scoped, auditable access that expires automatically after the workflow completes.

Configuring AWS OIDC trust policy

Create an IAM role with a trust policy that restricts assumption to specific repositories and branches. This prevents compromised workflows in other repos from accessing your production infrastructure.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:YOUR_ORG/YOUR_REPO:ref:refs/heads/main"
        }
      }
    }
  ]
}

Deployment job with OIDC authentication

deploy:
  needs: test
  if: github.ref == 'refs/heads/main' && github.event_name == 'push'
  runs-on: ubuntu-latest
  permissions:
    id-token: write
    contents: read
  steps:
    - uses: actions/checkout@v4
    - name: Configure AWS Credentials (OIDC)
      uses: aws-actions/configure-aws-credentials@v4
      with:
        role-to-assume: arn:aws:iam::ACCOUNT_ID:role/FastAPIDeployRole
        aws-region: us-east-1
    - name: Deploy to ECS
      run: |
        aws ecs update-service \
          --cluster prod-cluster \
          --service fastapi-service \
          --force-new-deployment
    - name: Wait for deployment stability
      run: |
        aws ecs wait services-stable \
          --cluster prod-cluster \
          --services fastapi-service

This approach eliminates secret rotation overhead entirely. For teams comparing deployment targets, review GitHub Actions vs GitLab CI to evaluate OIDC support across platforms.

What are common pitfalls when automating FastAPI deployments?

Even experienced teams stumble on subtle issues when automating Python API deployments. Based on production incidents I’ve resolved, these are the most frequent failure modes:

• Ignoring Pydantic V2 migration impacts: Validation errors changed format in V2. Tests passing locally may fail in CI if your test assertions expect V1 error structures. Always validate serialization round-trips explicitly.
• Missing health check endpoints: Deployments appear successful but traffic routes to unhealthy pods. Always implement /healthz and /readyz endpoints that verify database connectivity and dependency availability, not just return 200.
• Running migrations in entrypoint scripts: Concurrent pod startups cause migration race conditions. Run migrations as a separate init container or pre-deploy job with idempotent operations.
• Not setting resource limits: FastAPI workers can consume unbounded memory under load. Define CPU/memory requests and limits in Kubernetes manifests or ECS task definitions to prevent node exhaustion.
• Skipping dependency vulnerability scans: Add uv pip audit or trivy scanning as a required CI gate. Supply chain attacks targeting Python packages increased significantly through 2025–2026.

Addressing these proactively prevents 3 AM pages and compliance audit findings. For teams operating in regulated sectors, integrating SOC 2 compliance evidence collection directly into your FastAPI CI pipeline turns security validation from a quarterly burden into continuous assurance.

Implementing Production-Ready CI/CD for FastAPI with GitHub Actions

Effective CI/CD for FastAPI with GitHub Actions combines fast feedback loops, secure credential management, and observable deployments. Start with the async testing patterns and OIDC configuration above, then incrementally add container scanning, SLSA provenance attestation, and automated rollback triggers based on error budget consumption. If your team needs hands-on implementation support or architecture review for Python API platforms, reach out to discuss your specific deployment challenges.