ci.yml

name: CI

# Single CI workflow that runs both the pgaftest and Python test suites.
#
# Job dependency graph:
#
#   style_checker ──────┐
#   check_base_changed ─┤
#                       ├── (all must pass before any build job starts)
#   ensure_base  ───────┘
#               ├── build_run_images  (PG 14-19 → pgaf:run-pgN; installcheck runs inside build stage)
#               │       └── test_pgaftest   (spec jobs)
#               ├── build_pgaftest    (pgaf:pgaftest, built from PG17)
#               │       └── test_pgaftest   (same)
#               │       └── upgrade
#               └── build_test_images (PG 14-19 → pg_auto_failover_test:pgN)
#                       └── test_python    (PG × suite matrix)

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:

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

env:
  BASE: ghcr.io/hapostgres/pg_auto_failover/pgaf-base:bookworm

jobs:
  # ---------------------------------------------------------------------------
  # 0. Detect a docs-only change (docs/**, *.md, LICENSE) so the expensive
  #    build/test jobs below can skip themselves. A *skipped* job still
  #    reports a "skipped" conclusion under its required-check name, which
  #    branch protection treats as passing -- unlike a top-level
  #    push/pull_request `paths-ignore`, which would make the workflow never
  #    run at all and leave this repo's required status checks permanently
  #    pending on a docs-only PR.
  # ---------------------------------------------------------------------------
  check_docs_only:
    name: Check if this is a docs-only change
    runs-on: ubuntu-latest
    outputs:
      docs_only: ${{ steps.diff.outputs.docs_only }}
    steps:
      - uses: actions/checkout@v7.0.0
        with:
          fetch-depth: 0

      - name: Detect docs-only change
        id: diff
        run: |
          BASE_REF="${{ github.event.pull_request.base.sha || 'HEAD~1' }}"
          if git diff --name-only "${BASE_REF}"...HEAD | grep -qvE '^(docs/|.*\.md$|LICENSE$)'; then
            echo "docs_only=false" >> "$GITHUB_OUTPUT"
          else
            echo "docs_only=true"  >> "$GITHUB_OUTPUT"
          fi

  # ---------------------------------------------------------------------------
  # 1. Style check
  # ---------------------------------------------------------------------------
  style_checker:
    name: Style check
    needs: check_docs_only
    if: needs.check_docs_only.outputs.docs_only != 'true'
    runs-on: ubuntu-latest
    container: citus/stylechecker:no-py
    steps:
      - uses: actions/checkout@v7.0.0

      - name: Set safe directory for git
        run: git config --global --add safe.directory ${GITHUB_WORKSPACE}

      - name: Check C formatting
        run: citus_indent --check

      - name: Check banned functions
        run: ci/banned.h.sh

  # ---------------------------------------------------------------------------
  # 2a. Detect whether Dockerfile.base changed in this PR/push so that
  #     ensure_base knows to force-rebuild rather than reuse the cached image.
  # ---------------------------------------------------------------------------
  check_base_changed:
    name: Check if Dockerfile.base changed
    needs: check_docs_only
    if: needs.check_docs_only.outputs.docs_only != 'true'
    runs-on: ubuntu-latest
    outputs:
      changed: ${{ steps.diff.outputs.changed }}
    steps:
      - uses: actions/checkout@v7.0.0
        with:
          fetch-depth: 0

      - name: Detect Dockerfile.base change
        id: diff
        run: |
          BASE_REF="${{ github.event.pull_request.base.sha || 'HEAD~1' }}"
          if git diff --name-only "${BASE_REF}"...HEAD | grep -q '^Dockerfile\.base$'; then
            echo "changed=true"  >> "$GITHUB_OUTPUT"
          else
            echo "changed=false" >> "$GITHUB_OUTPUT"
          fi

  # ---------------------------------------------------------------------------
  # 2b. Ensure base image — pull from ghcr.io or build+push on cache miss.
  #     Runs in parallel with style_checker; build jobs wait for both.
  #     Fast path (image exists and Dockerfile.base unchanged): ~5 s check.
  #     Slow path (first run or Dockerfile.base changed): ~20 min build.
  # ---------------------------------------------------------------------------
  ensure_base:
    name: Ensure base image
    needs: check_base_changed
    uses: ./.github/workflows/base-image.yml
    with:
      force_rebuild: ${{ needs.check_base_changed.outputs.changed == 'true' }}
    permissions:
      contents: read
      packages: write

  # ---------------------------------------------------------------------------
  # 3a. Build pgaf:run images — lean runtime images for pgaftest node containers.
  #     The build stage also runs installcheck (pg_virtualenv + pg_regress).
  #     One image per Postgres major version; uploaded as artifacts for test jobs.
  # ---------------------------------------------------------------------------
  build_run_images:
    name: Build run image (PG${{ matrix.PGVERSION }})
    needs: [style_checker, ensure_base]
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: read
    strategy:
      fail-fast: false
      matrix:
        PGVERSION: [14, 15, 16, 17, 18, 19]

    steps:
      - uses: actions/checkout@v7.0.0

      - name: Generate git-version.h
        run: make version

      - name: Log in to ghcr.io
        uses: docker/login-action@v4.4.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up Docker BuildKit
        uses: docker/setup-buildx-action@v4.2.0

      - name: Build pgaf:run-pg${{ matrix.PGVERSION }}
        run: |
          docker buildx build \
            --cache-from type=gha,scope=pgaf-run-pg${{ matrix.PGVERSION }} \
            --cache-to   type=gha,mode=max,scope=pgaf-run-pg${{ matrix.PGVERSION }} \
            --build-arg PGVERSION=${{ matrix.PGVERSION }} \
            --build-arg BASE=${{ env.BASE }} \
            --target run \
            -t pgaf:run-pg${{ matrix.PGVERSION }} \
            --load \
            .

      - name: Save image to tarball
        run: |
          docker save pgaf:run-pg${{ matrix.PGVERSION }} \
            | gzip > /tmp/pgaf-run-pg${{ matrix.PGVERSION }}.tar.gz

      - name: Upload run image artifact
        uses: actions/upload-artifact@v7.0.1
        with:
          name: pgaf-run-image-pg${{ matrix.PGVERSION }}
          path: /tmp/pgaf-run-pg${{ matrix.PGVERSION }}.tar.gz
          retention-days: 1

  # ---------------------------------------------------------------------------
  # 3b. Build pgaf:pgaftest — test-runner image with Docker CLI + pgaftest binary.
  #     Built once (using PG17 as the compilation target).
  # ---------------------------------------------------------------------------
  build_pgaftest:
    name: Build pgaftest image
    needs: [style_checker, ensure_base]
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: read
    env:
      PGVERSION: 17

    steps:
      - uses: actions/checkout@v7.0.0

      - name: Generate git-version.h
        run: make version

      - name: Log in to ghcr.io
        uses: docker/login-action@v4.4.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up Docker BuildKit
        uses: docker/setup-buildx-action@v4.2.0

      - name: Build pgaf:pgaftest
        run: |
          docker buildx build \
            --cache-from type=gha,scope=pgaf-run-pg${{ env.PGVERSION }} \
            --cache-from type=gha,scope=pgaf-pgaftest \
            --cache-to   type=gha,mode=max,scope=pgaf-pgaftest \
            --build-arg PGVERSION=${{ env.PGVERSION }} \
            --build-arg BASE=${{ env.BASE }} \
            --target pgaftest \
            -t pgaf:pgaftest \
            --load \
            .

      - name: Save image to tarball
        run: docker save pgaf:pgaftest | gzip > /tmp/pgaf-pgaftest.tar.gz

      - name: Upload pgaftest image artifact
        uses: actions/upload-artifact@v7.0.1
        with:
          name: pgaftest-image
          path: /tmp/pgaf-pgaftest.tar.gz
          retention-days: 1

  # ---------------------------------------------------------------------------
  # 3c. Build pg_auto_failover_test images — full test images that include the
  #     Python test suite (pytest) and all source.  Used by test_python jobs.
  # ---------------------------------------------------------------------------
  build_test_images:
    name: Build test image (PG${{ matrix.PGVERSION }})
    needs: [style_checker, ensure_base]
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: read
    strategy:
      fail-fast: false
      matrix:
        PGVERSION: [14, 15, 16, 17, 18, 19]

    steps:
      - uses: actions/checkout@v7.0.0

      - name: Generate git-version.h
        run: make version

      - name: Log in to ghcr.io
        uses: docker/login-action@v4.4.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up Docker BuildKit
        uses: docker/setup-buildx-action@v4.2.0

      - name: Build pg_auto_failover_test:pg${{ matrix.PGVERSION }}
        run: |
          docker buildx build \
            --cache-from type=gha,scope=pgaf-run-pg${{ matrix.PGVERSION }} \
            --cache-from type=gha,scope=pgaf-test-pg${{ matrix.PGVERSION }} \
            --cache-to   type=gha,mode=max,scope=pgaf-test-pg${{ matrix.PGVERSION }} \
            --build-arg PGVERSION=${{ matrix.PGVERSION }} \
            --build-arg BASE=${{ env.BASE }} \
            --target test \
            -t pg_auto_failover_test:pg${{ matrix.PGVERSION }} \
            --load \
            .

      - name: Save image to tarball
        run: |
          docker save pg_auto_failover_test:pg${{ matrix.PGVERSION }} \
            | zstd -T0 -3 > /tmp/pg_auto_failover_test-pg${{ matrix.PGVERSION }}.tar.zst

      - name: Upload test image artifact
        uses: actions/upload-artifact@v7.0.1
        with:
          name: pg-test-image-${{ matrix.PGVERSION }}
          path: /tmp/pg_auto_failover_test-pg${{ matrix.PGVERSION }}.tar.zst
          retention-days: 1

  # ---------------------------------------------------------------------------
  # 4a. pgaftest suite — spec-driven tests using the pgaftest binary.
  #     Fast/medium schedules run all 6 PG versions; slow schedules PG17 only.
  # ---------------------------------------------------------------------------
  test_pgaftest:
    name: pgaftest / ${{ matrix.schedule }} (PG${{ matrix.PGVERSION }})
    needs: [build_run_images, build_pgaftest]
    runs-on: ubuntu-latest
    timeout-minutes: 25
    strategy:
      fail-fast: false
      matrix:
        include:
          # quick: basic_operation, basic_operation_listen_flag, config_get_set, skip_pg_hba
          - { PGVERSION: 14, schedule: quick }
          - { PGVERSION: 15, schedule: quick }
          - { PGVERSION: 16, schedule: quick }
          - { PGVERSION: 17, schedule: quick }
          - { PGVERSION: 18, schedule: quick }
          - { PGVERSION: 19, schedule: quick }
          # node: create_standby_with_pgdata, maintenance_and_drop, auth,
          #       monitor_disabled, replace_monitor, extension_update,
          #       debian_clusters, tablespaces, fsm_step_report_advance,
          #       replication_stall/demote_timeout/timeline_fork deadlocks
          #       — see tests/tap/schedules/node.sch for the full list
          - { PGVERSION: 14, schedule: node }
          - { PGVERSION: 15, schedule: node }
          - { PGVERSION: 16, schedule: node }
          - { PGVERSION: 17, schedule: node }
          - { PGVERSION: 18, schedule: node }
          - { PGVERSION: 19, schedule: node }
          # ssl: enable_ssl, ssl_self_signed, ssl_cert
          - { PGVERSION: 14, schedule: ssl }
          - { PGVERSION: 15, schedule: ssl }
          - { PGVERSION: 16, schedule: ssl }
          - { PGVERSION: 17, schedule: ssl }
          - { PGVERSION: 18, schedule: ssl }
          - { PGVERSION: 19, schedule: ssl }
          # slow schedules: PG17 only (FSM logic, not version-specific code paths)
          - { PGVERSION: 17, schedule: multi-alternate }
          - { PGVERSION: 17, schedule: multi-misc }
          - { PGVERSION: 17, schedule: multi-async }
          - { PGVERSION: 17, schedule: node-fsm-gaps }
          - { PGVERSION: 17, schedule: citus-1 }
          - { PGVERSION: 17, schedule: citus-2 }
          # citus on PG18 (supported); allow failure until officially validated
          - { PGVERSION: 18, schedule: citus-1, continue-on-error: true }
          - { PGVERSION: 18, schedule: citus-2, continue-on-error: true }
          # PG19: no Citus release yet (CITUSTAG_19=none) — citus schedules omitted

    steps:
      - uses: actions/checkout@v7.0.0

      - name: Download pgaf:run image (PG${{ matrix.PGVERSION }})
        uses: actions/download-artifact@v8.0.1
        with:
          name: pgaf-run-image-pg${{ matrix.PGVERSION }}
          path: /tmp

      - name: Load pgaf:run image
        run: docker load < /tmp/pgaf-run-pg${{ matrix.PGVERSION }}.tar.gz

      - name: Download pgaf:pgaftest image
        uses: actions/download-artifact@v8.0.1
        with:
          name: pgaftest-image
          path: /tmp

      - name: Load pgaf:pgaftest image
        run: docker load < /tmp/pgaf-pgaftest.tar.gz

      - name: Run schedule ${{ matrix.schedule }}
        timeout-minutes: 20
        run: |
          mkdir -p /tmp/pgaftest && chmod 777 /tmp/pgaftest
          DOCKER_GID=$(stat -c '%g' /var/run/docker.sock)
          docker run --rm \
            --user root \
            --group-add "${DOCKER_GID}" \
            -v /var/run/docker.sock:/var/run/docker.sock \
            -v /tmp/pgaftest:/tmp/pgaftest \
            -v "$(pwd)":/work:ro \
            -w /work \
            -e PGAF_IMAGE=pgaf:run-pg${{ matrix.PGVERSION }} \
            -e PGVERSION=${{ matrix.PGVERSION }} \
            -e PGAFTEST_HOST_WORK_DIR="$(pwd)" \
            pgaf:pgaftest \
            pgaftest run --schedule tests/tap/schedules/${{ matrix.schedule }}.sch

  # ---------------------------------------------------------------------------
  # 4b. pgaftest upgrade test — binary + extension swap without restart.
  #     Pinned to PG16 (the upgrade path always runs N-1 → current).
  # ---------------------------------------------------------------------------
  upgrade:
    name: pgaftest / upgrade
    needs: [build_pgaftest]
    runs-on: ubuntu-latest
    timeout-minutes: 30
    env:
      PGVERSION: 16

    steps:
      - uses: actions/checkout@v7.0.0
        with:
          fetch-depth: 0

      - name: Log in to ghcr.io
        uses: docker/login-action@v4.4.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Download pgaf:pgaftest image
        uses: actions/download-artifact@v8.0.1
        with:
          name: pgaftest-image
          path: /tmp

      - name: Load pgaf:pgaftest image
        run: docker load < /tmp/pgaf-pgaftest.tar.gz

      - name: Generate git-version.h
        run: make version

      - name: Build pgaf:next (current branch, PG${{ env.PGVERSION }})
        run: make -C tests/upgrade pgaf-next PGVERSION=${{ env.PGVERSION }}

      - name: Build pgaf:current (previous release, PG${{ env.PGVERSION }})
        run: make -C tests/upgrade pgaf-current PGVERSION=${{ env.PGVERSION }}

      - name: Run upgrade spec
        timeout-minutes: 25
        run: |
          mkdir -p /tmp/pgaftest && chmod 777 /tmp/pgaftest
          DOCKER_GID=$(stat -c '%g' /var/run/docker.sock)
          docker run --rm \
            --user root \
            --group-add "${DOCKER_GID}" \
            -v /var/run/docker.sock:/var/run/docker.sock \
            -v /tmp/pgaftest:/tmp/pgaftest \
            -v "$(pwd)":/work:ro \
            -w /work \
            -e PGVERSION=${{ env.PGVERSION }} \
            -e PGAFTEST_HOST_WORK_DIR="$(pwd)" \
            pgaf:pgaftest \
            pgaftest run tests/tap/specs/upgrade.pgaf

  # ---------------------------------------------------------------------------
  # 4c. Python test suite (pytest) — run inside the pg_auto_failover_test image.
  #     (installcheck runs inside the build stage of build_run_images)
  #     Matrix: PG 14-17 × {multi, single, monitor, ssl, citus} + tablespaces.
  # ---------------------------------------------------------------------------
  test_python:
    name: pytest / ${{ matrix.TEST }} (PG${{ matrix.PGVERSION }})
    needs: build_test_images
    runs-on: ubuntu-latest
    timeout-minutes: 20
    strategy:
      fail-fast: false
      matrix:
        PGVERSION: [14, 15, 16, 17, 18, 19]
        TEST: [multi, single, monitor, ssl, citus]
        exclude:
          # Citus does not support PG19 yet
          - PGVERSION: 19
            TEST: citus
        include:
          - PGVERSION: 14
            TEST: tablespaces
          # Allow citus failures on PG18 until officially validated
          - PGVERSION: 18
            TEST: citus
            continue-on-error: true

    steps:
      - uses: actions/checkout@v7.0.0

      - name: Download test image (PG${{ matrix.PGVERSION }})
        uses: actions/download-artifact@v8.0.1
        with:
          name: pg-test-image-${{ matrix.PGVERSION }}

      - name: Load test image
        run: |
          zstd -d --stdout \
            pg_auto_failover_test-pg${{ matrix.PGVERSION }}.tar.zst \
            | docker load

      - name: Set environment variables
        run: |
          echo "PGVERSION=${{ matrix.PGVERSION }}" >> $GITHUB_ENV
          echo "TEST=${{ matrix.TEST }}"           >> $GITHUB_ENV
          echo "TRAVIS_BUILD_DIR=$(pwd)"           >> $GITHUB_ENV

      - name: Run pytest / ${{ matrix.TEST }} (PG${{ matrix.PGVERSION }})
        # citus is the heaviest TEST value in this matrix (6 files, ~76 items,
        # several multi-coordinator/multi-worker convergence waits) and has
        # been seen to run right up against a 15-minute step timeout while
        # still making forward progress, not stuck -- e.g. citus (PG14)
        # timed out mid-suite on 2026-07-29 with ~4-5 minutes of the job's
        # own 20-minute ceiling (see above) left completely unused. 18
        # minutes gives real headroom while still leaving margin under the
        # job-level timeout once checkout/download/docker-load are counted.
        timeout-minutes: 18
        run: make run-test-prebuilt