[CHORE]: Add CI workflow to validate Alembic migration history is linear

[cafalchio]

Description

Add a CI workflow to validate that the Alembic migration history remains linear (single head) to prevent migration conflicts.

Current State

The Alembic migration history currently has 5 merge points where parallel development branches were consolidated. While these have been resolved, future branches could create similar issues.

Proposed Solution

Add a GitHub Actions workflow that:

1. Runs alembic heads to check for multiple heads
2. Fails the CI if more than one head is detected
3. Runs on PR and push to main/develop branches

Implementation

name: Validate Alembic History
on:
  pull_request:
    paths:
      - 'mcpgateway/alembic/versions/**'
  push:
    branches: [main, develop]
    paths:
      - 'mcpgateway/alembic/versions/**'

jobs:
  check-alembic-history:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: |
          pip install alembic sqlalchemy
      - name: Check for single head
        run: |
          cd mcpgateway
          HEADS=$(alembic heads | wc -l)
          if [ $HEADS -ne 1 ]; then
            echo "Error: Multiple Alembic heads detected"
            alembic heads
            exit 1
          fi
          echo "✓ Single Alembic head confirmed"

Benefits

• Catches migration branching issues early in PR review
• Prevents merge conflicts in migration history
• Enforces linear migration chain as documented in AGENTS.md

Related

• See alembic.md for current migration history visualization
• See AGENTS.md Alembic section for migration best practices