ci.yml

---
# Pullbox CI Pipeline
# Quality gate — lint, typecheck, test, migration check, accessibility, E2E.
# GitHub Actions is the canonical PR CI runner. Pull request pushes run a
# cheap preflight until same-repository maintainer PRs receive `ci:full`.
#
# Security: All actions pinned to full SHA. No pull_request_target.
# See: docs/development/INFRASTRUCTURE.md

name: CI

on:
  pull_request:
    branches:
      - develop
      - main
    types:
      - opened
      - synchronize
      - reopened
      - ready_for_review
      - labeled
      - unlabeled
  workflow_dispatch:
    inputs:
      e2e_diagnostics:
        description: Retain E2E failure video and traces
        required: false
        type: boolean
        default: false

permissions:
  contents: read

concurrency:
  group: ci-${{ github.event.pull_request.number || github.ref || github.run_id }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

env:
  E2E_WORKERS: "3"
  E2E_VIDEO_MODE: "${{ github.event_name == 'workflow_dispatch' && inputs.e2e_diagnostics && 'retain-on-failure' || 'off' }}"
  PULLBOX_E2E_TRACE: "${{ github.event_name == 'workflow_dispatch' && inputs.e2e_diagnostics && 'true' || 'false' }}"
  PYTHON_DEFAULT: "3.14"
  PYTEST_WORKERS: "5"

jobs:
  release_sync_check:
    name: Release Sync Check
    runs-on: ubuntu-latest
    timeout-minutes: 5
    outputs:
      is_sync: ${{ steps.release-sync.outputs.is_sync }}
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0

      - name: Detect safe post-release sync PR
        id: release-sync
        env:
          RELEASE_SYNC_EVENT_NAME: ${{ github.event_name }}
          RELEASE_SYNC_BASE_REF: ${{ github.base_ref || '' }}
          RELEASE_SYNC_HEAD_REF: ${{ github.head_ref || '' }}
          RELEASE_SYNC_REPOSITORY: ${{ github.repository }}
          RELEASE_SYNC_HEAD_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name || '' }}
          RELEASE_SYNC_ACTOR: ${{ github.actor }}
        run: |
          git fetch --no-tags origin main:refs/remotes/origin/main
          if ! git cat-file -e origin/main:.github/scripts/validate-release-sync-pr.py 2>/dev/null; then
            echo "is_sync=false" >> "$GITHUB_OUTPUT"
            echo "reason=trusted release sync validator is not available on origin/main yet" >> "$GITHUB_OUTPUT"
            echo "release_sync=false"
            echo "reason=trusted release sync validator is not available on origin/main yet"
            exit 0
          fi
          git show origin/main:.github/scripts/validate-release-sync-pr.py > /tmp/pullbox-release-sync-validator.py
          python /tmp/pullbox-release-sync-validator.py

  full_ci_check:
    name: Full CI Gate
    runs-on: ubuntu-latest
    timeout-minutes: 5
    outputs:
      run_full: ${{ steps.gate.outputs.run_full }}
      label_required: ${{ steps.gate.outputs.label_required }}
    permissions:
      contents: read
    steps:
      - name: Resolve full CI gate
        id: gate
        run: |
          echo "run_full=${{ github.event_name == 'workflow_dispatch' || (github.event_name == 'pull_request' && !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name != github.repository || github.actor == 'dependabot[bot]' || startsWith(github.event.pull_request.head.ref, 'dependabot/') || contains(github.event.pull_request.labels.*.name, 'ci:full'))) }}" >> "$GITHUB_OUTPUT"
          echo "label_required=${{ github.event_name == 'pull_request' && !github.event.pull_request.draft && github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]' && !startsWith(github.event.pull_request.head.ref, 'dependabot/') && !contains(github.event.pull_request.labels.*.name, 'ci:full') }}" >> "$GITHUB_OUTPUT"

  # ──────────────────────────────────────────────
  # Job 1: Quality Gate (~45s)
  # ──────────────────────────────────────────────
  quality-gate:
    name: Quality Gate
    needs: [release_sync_check, full_ci_check]
    if: needs.release_sync_check.outputs.is_sync != 'true'
    runs-on: ${{ fromJSON(((github.event_name == 'pull_request' && (github.event.pull_request.head.repo.full_name != github.repository || github.actor == 'dependabot[bot]')) || vars.PULLBOX_CHECKS_RUNNER == 'github-hosted') && '["ubuntu-latest"]' || '["self-hosted","Linux","X64","ci"]') }}
    timeout-minutes: 15
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ env.PYTHON_DEFAULT }}

      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: "24"

      - name: Setup runner-local venv
        run: .github/scripts/setup-runner-venv.sh "dev"

      - name: Runner preflight
        run: .github/scripts/preflight-runner.sh python node

      - name: Ruff lint
        run: ruff check src/ tests/

      - name: Ruff format check
        run: ruff format --check src/ tests/

      - name: Install Tailwind
        run: npm ci

      - name: Rebuild Tailwind CSS
        run: npm run css:build

      - name: Check for uncommitted CSS changes
        run: |
          git diff --exit-code src/pullbox/ui/static/css/tailwind.css || {
            echo "::error::Tailwind CSS output is stale. Run 'make css-build' and commit the result."
            exit 1
          }
          echo "✅ Tailwind CSS is up to date"

  # ──────────────────────────────────────────────
  # Job 2: Type Check (~1-2 min)
  # ──────────────────────────────────────────────
  typecheck:
    name: Type Check
    needs: [release_sync_check, full_ci_check]
    if: needs.release_sync_check.outputs.is_sync != 'true' && needs.full_ci_check.outputs.run_full == 'true'
    runs-on: ${{ fromJSON(((github.event_name == 'pull_request' && (github.event.pull_request.head.repo.full_name != github.repository || github.actor == 'dependabot[bot]')) || vars.PULLBOX_CHECKS_RUNNER == 'github-hosted') && '["ubuntu-latest"]' || '["self-hosted","Linux","X64","ci"]') }}
    timeout-minutes: 15
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ env.PYTHON_DEFAULT }}

      - name: Setup runner-local venv
        run: .github/scripts/setup-runner-venv.sh "dev"

      - name: Runner preflight
        run: .github/scripts/preflight-runner.sh python

      - name: Mypy
        run: mypy src/pullbox/

  # ──────────────────────────────────────────────
  # Job 3: Tests + Coverage (matrix: 3.12, 3.13, 3.14)
  # Every version runs the complete suite and publishes coverage. The blocking
  # 90% release gate follows the production/default Python 3.14 runtime.
  # ──────────────────────────────────────────────
  test:
    name: Test (Python ${{ matrix.python-version }})
    runs-on: ${{ fromJSON(((github.event_name == 'pull_request' && (github.event.pull_request.head.repo.full_name != github.repository || github.actor == 'dependabot[bot]')) || vars.PULLBOX_CHECKS_RUNNER == 'github-hosted') && '["ubuntu-latest"]' || '["self-hosted","Linux","X64","ci"]') }}
    needs: [release_sync_check, full_ci_check, quality-gate, typecheck, alembic-check]
    if: needs.release_sync_check.outputs.is_sync != 'true' && needs.full_ci_check.outputs.run_full == 'true'
    timeout-minutes: 30
    permissions:
      contents: read
    strategy:
      fail-fast: false
      matrix:
        include:
          - python-version: "3.12"
            coverage_fail_under: 0
          - python-version: "3.13"
            coverage_fail_under: 0
          - python-version: "3.14"
            coverage_fail_under: 90
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ matrix.python-version }}

      - name: Setup runner-local venv
        run: .github/scripts/setup-runner-venv.sh "dev"

      - name: Runner preflight
        run: .github/scripts/preflight-runner.sh python

      - name: Run tests with coverage
        run: |
          pytest tests/ \
            --ignore=tests/e2e \
            -n "${PYTEST_WORKERS}" \
            --dist=worksteal \
            --cov=pullbox \
            --cov-report=xml \
            --cov-report=term-missing \
            --cov-fail-under="${COVERAGE_FAIL_UNDER}" \
            --junitxml=test-results.xml \
            -v
        env:
          COVERAGE_FAIL_UNDER: ${{ matrix.coverage_fail_under }}
          PULLBOX_SECRET_KEY: test-ci-key
          PYTEST_WORKERS: ${{ env.PYTEST_WORKERS }}

      - name: Upload coverage report
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: coverage-report-py${{ matrix.python-version }}
          path: coverage.xml
          if-no-files-found: error
          retention-days: 30

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: test-results-py${{ matrix.python-version }}
          path: test-results.xml
          retention-days: 30

  # ──────────────────────────────────────────────
  # Job 4: Alembic Migration Sanity Check
  # ──────────────────────────────────────────────
  alembic-check:
    name: Migration Check
    needs: [release_sync_check, full_ci_check]
    if: needs.release_sync_check.outputs.is_sync != 'true' && needs.full_ci_check.outputs.run_full == 'true'
    runs-on: ${{ fromJSON(((github.event_name == 'pull_request' && (github.event.pull_request.head.repo.full_name != github.repository || github.actor == 'dependabot[bot]')) || vars.PULLBOX_CHECKS_RUNNER == 'github-hosted') && '["ubuntu-latest"]' || '["self-hosted","Linux","X64","ci"]') }}
    timeout-minutes: 15
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ env.PYTHON_DEFAULT }}

      - name: Setup runner-local venv
        run: .github/scripts/setup-runner-venv.sh "dev"

      - name: Runner preflight
        run: .github/scripts/preflight-runner.sh python

      - name: Verify migrations apply from empty DB
        run: |
          alembic -c alembic/alembic.ini upgrade head
          echo "✅ Migrations applied successfully"
          alembic -c alembic/alembic.ini downgrade base
          echo "✅ Downgrade to base successful"
        env:
          PULLBOX_SECRET_KEY: test-ci-key
          PULLBOX_DB_URL: "sqlite+aiosqlite:///test_migration.db"

      - name: Verify app boots after migration
        run: |
          alembic -c alembic/alembic.ini upgrade head
          timeout 10 python -c "
          import asyncio
          from pullbox.app import create_app
          app = create_app()
          print('✅ App factory created successfully')
          "
        env:
          PULLBOX_SECRET_KEY: test-ci-key
          PULLBOX_DB_URL: "sqlite+aiosqlite:///test_boot.db"

  # ──────────────────────────────────────────────
  # Job 5: Accessibility Checks (contrast + WCAG scans in Chromium)
  # ──────────────────────────────────────────────
  accessibility:
    name: Accessibility Checks
    runs-on: ${{ fromJSON(((github.event_name == 'pull_request' && (github.event.pull_request.head.repo.full_name != github.repository || github.actor == 'dependabot[bot]')) || vars.PULLBOX_CHECKS_RUNNER == 'github-hosted') && '["ubuntu-latest"]' || '["self-hosted","Linux","X64","checks"]') }}
    needs: [release_sync_check, full_ci_check, quality-gate, typecheck, alembic-check]
    if: needs.release_sync_check.outputs.is_sync != 'true' && needs.full_ci_check.outputs.run_full == 'true'
    timeout-minutes: 30
    permissions:
      contents: read
    env:
      PULLBOX_SECRET_KEY: test-ci-key
      PULLBOX_DB_URL: "sqlite+aiosqlite:///test_a11y_${{ github.run_id }}_${{ github.run_attempt }}.db"
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ env.PYTHON_DEFAULT }}

      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: "24"

      - name: Install Node dependencies
        run: npm ci

      - name: Setup runner-local venv
        run: .github/scripts/setup-runner-venv.sh "dev,e2e"

      - name: Runner preflight
        run: .github/scripts/preflight-runner.sh python node playwright

      - name: Install Playwright Chromium
        run: playwright install chromium

      - name: Run contrast audit
        run: python scripts/check_ui_contrast.py

      - name: Run accessibility browser tests
        run: |
          mkdir -p test-results/accessibility test-results/e2e
          pytest tests/e2e/ \
            -v \
            -m accessibility \
            --browser chromium \
            --video "${E2E_VIDEO_MODE}" \
            --screenshot only-on-failure \
            --full-page-screenshot \
            --output=test-results/e2e \
            --junitxml=test-results/accessibility-junit.xml

      - name: Upload accessibility JUnit results
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: accessibility-results
          path: test-results/accessibility-junit.xml
          retention-days: 14

      - name: Upload accessibility failure artifacts
        if: failure() || cancelled()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: accessibility-artifacts
          path: test-results/
          if-no-files-found: ignore
          retention-days: 14

      - name: Accessibility job summary
        if: always()
        run: |
          {
            echo "## Accessibility Checks"
            echo ""
            echo "- Contrast audit: semantic color token gate"
            echo "- Browser audit: marked accessibility E2E coverage"
            echo "- Failure artifacts: uploaded only when the job fails or is canceled"
          } >> "$GITHUB_STEP_SUMMARY"

  # ──────────────────────────────────────────────
  # Job 6: E2E Tests (per-browser isolated pytest sessions, after tests pass)
  # ──────────────────────────────────────────────
  e2e:
    name: E2E Tests (${{ matrix.browser }})
    runs-on: ${{ fromJSON(((github.event_name == 'pull_request' && (github.event.pull_request.head.repo.full_name != github.repository || github.actor == 'dependabot[bot]')) || vars.PULLBOX_CHECKS_RUNNER == 'github-hosted') && '["ubuntu-latest"]' || '["self-hosted","Linux","X64","ci"]') }}
    needs: [release_sync_check, full_ci_check, test]
    if: needs.release_sync_check.outputs.is_sync != 'true' && needs.full_ci_check.outputs.run_full == 'true'
    timeout-minutes: 30
    permissions:
      contents: read
    strategy:
      fail-fast: false
      matrix:
        include:
          - browser: chromium
            pytest_extra_args: ""
          - browser: firefox
            pytest_extra_args: "--durations=25 --durations-min=1.0"
    env:
      PULLBOX_SECRET_KEY: test-ci-key
      PULLBOX_RATE_LIMIT_ENABLED: "false"
      PULLBOX_DB_URL: "sqlite+aiosqlite:///test_e2e_${{ github.run_id }}_${{ github.run_attempt }}_${{ matrix.browser }}.db"
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ env.PYTHON_DEFAULT }}

      - name: Setup runner-local venv
        run: .github/scripts/setup-runner-venv.sh "dev,e2e"

      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: "24"

      - name: Install Node dependencies
        run: npm ci

      - name: Runner preflight
        run: .github/scripts/preflight-runner.sh python node playwright

      - name: Install Playwright browsers
        run: playwright install ${{ matrix.browser }}

      - name: Run E2E tests
        run: |
          mkdir -p test-results/e2e test-results/playwright
          pytest tests/e2e/ \
            -v \
            -m "not accessibility" \
            -n "${E2E_WORKERS}" \
            --dist=worksteal \
            --browser ${{ matrix.browser }} \
            ${{ matrix.pytest_extra_args }} \
            --video "${E2E_VIDEO_MODE}" \
            --screenshot only-on-failure \
            --full-page-screenshot \
            --output=test-results/e2e \
            --junitxml=test-results/e2e-junit.xml

      - name: Upload E2E JUnit results
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: e2e-results-${{ matrix.browser }}
          path: test-results/e2e-junit.xml
          retention-days: 14

      - name: Upload Playwright failure artifacts
        if: failure() || cancelled()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: playwright-artifacts-${{ matrix.browser }}
          path: test-results/
          if-no-files-found: ignore
          retention-days: 14

      - name: E2E job summary
        if: always()
        run: |
          {
            echo "## E2E Checks (${{ matrix.browser }})"
            echo ""
            echo "- Browser: ${{ matrix.browser }}"
            echo "- Failure artifacts: uploaded only when the job fails or is canceled"
          } >> "$GITHUB_STEP_SUMMARY"

  # Stable aggregate required check for branch rulesets.
  ci-required:
    name: CI Required
    runs-on: ubuntu-latest
    needs:
      - release_sync_check
      - full_ci_check
      - quality-gate
      - typecheck
      - alembic-check
      - test
      - accessibility
      - e2e
    if: always()
    timeout-minutes: 5
    permissions:
      contents: read
    steps:
      - name: Verify required CI jobs
        env:
          NEEDS_CONTEXT: ${{ toJson(needs) }}
          RELEASE_SYNC_PR: ${{ needs.release_sync_check.outputs.is_sync }}
          RUN_FULL: ${{ needs.full_ci_check.outputs.run_full }}
          LABEL_REQUIRED: ${{ needs.full_ci_check.outputs.label_required }}
        run: |
          python - <<'PY'
          import json
          import os
          import sys

          needs = json.loads(os.environ["NEEDS_CONTEXT"])
          release_sync_pr = os.environ["RELEASE_SYNC_PR"].lower() == "true"
          run_full = os.environ["RUN_FULL"].lower() == "true"
          label_required = os.environ["LABEL_REQUIRED"].lower() == "true"
          if release_sync_pr:
              release_sync = needs.get("release_sync_check", {}).get("result")
              if release_sync != "success":
                  print(f"Release sync validation failed: {release_sync}", file=sys.stderr)
                  sys.exit(1)
              unexpected = {
                  name: info.get("result")
                  for name, info in needs.items()
                  if name != "release_sync_check" and info.get("result") not in {"skipped", "success"}
              }
              if unexpected:
                  print(f"Release sync fast path saw unexpected job results: {unexpected}", file=sys.stderr)
                  sys.exit(1)
              print("Release sync fast path validated; heavyweight CI jobs intentionally skipped.")
              sys.exit(0)

          if not run_full:
              preflight = needs.get("quality-gate", {}).get("result")
              if preflight != "success":
                  print(f"CI preflight did not pass: {preflight}", file=sys.stderr)
                  sys.exit(1)
              if label_required:
                  print("CI preflight passed. Add the ci:full label when the PR is ready for the full required gate.", file=sys.stderr)
              else:
                  print("CI preflight passed, but full CI was intentionally not requested for this PR state.", file=sys.stderr)
              sys.exit(1)

          failed = {
              name: info.get("result")
              for name, info in needs.items()
              if info.get("result") != "success"
          }
          if failed:
              print(f"Required CI jobs did not all pass: {failed}", file=sys.stderr)
              sys.exit(1)
          print("All required CI jobs passed.")
          PY