ci-cd

ci-cd

Practical CI/CD patterns for Python/FastAPI and Node/Astro/Next.js projects using GitHub Actions. Covers pipeline structure, secrets management, Docker image builds, staged deployments, and zero-downtime restarts.

1) Pipeline Mental Model

Code push → Lint/Type-check → Unit tests → Build image → Push to registry
                                                              ↓
                                            Deploy to VPS (pull + restart)
                                                              ↓
                                            Health check → rollback if fail

Branch strategy:

• main → production deploy
• feature/* / development → run tests only, no deploy
• release/* → staging deploy

2) Standard GitHub Actions Workflow

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: ["**"]
  pull_request:
    branches: [main, development]

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

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: "pip"

      - name: Install dependencies
        run: pip install -r requirements.txt -r requirements-dev.txt

      - name: Lint
        run: |
          ruff check app/ shared/ --output-format=github
          mypy app/ --ignore-missing-imports

      - name: Test
        env:
          TEST_DATABASE_URL: postgresql://postgres:postgres@localhost:5432/test_db
          MOCK_MODE: "true"
          JWT_SECRET_KEY: test-secret
        run: pytest tests/ -v --tb=short -m "not slow"

    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: test_db
        ports: ["5432:5432"]
        options: >-
          --health-cmd pg_isready
          --health-interval 5s
          --health-timeout 3s
          --health-retries 5

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    needs: []   # add lint-and-test job name here if in same file
    environment: production

    steps:
      - uses: actions/checkout@v4

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            ghcr.io/${{ github.repository }}:latest
            ghcr.io/${{ github.repository }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
        env:
          DOCKER_BUILDKIT: 1

      - name: Deploy to VPS
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.VPS_HOST }}
          username: ${{ secrets.VPS_USER }}
          key: ${{ secrets.VPS_SSH_KEY }}
          script: |
            cd /opt/myapp
            docker pull ghcr.io/${{ github.repository }}:latest
            docker compose up -d --no-deps --build app
            sleep 5
            docker compose ps | grep "Up" || (echo "Deploy failed" && exit 1)