python-react-publish.yml

name: Reusable Python+React Publish

# Reusable tag-triggered publish workflow.
# Sequencing: test-* → docker → release
# - All test-* jobs must pass before docker push
# - docker push must succeed before release creation
# This guarantees: a tag never publishes a GitHub release without a matching
# image in GHCR. If the docker push fails, no release is created.

on:
  workflow_call:
    inputs:
      python-version:
        type: string
        default: "3.14"
      bun-version-file:
        type: string
        default: ".bun-version"
      bun-version:
        type: string
        default: ""
      enable-e2e:
        type: boolean
        default: true
      enable-translations:
        type: boolean
        default: false
      enable-bootstrap-token:
        type: boolean
        default: false
      enable-api-freshness-check:
        type: boolean
        default: true
      runner-os:
        type: string
        default: ubuntu-latest
      security-tripwire-script:
        type: string
        default: ""
      image-name:
        type: string
        required: true
      release-name-prefix:
        # E.g. "TideWatch v" → produces "TideWatch v3.9.2"
        type: string
        required: true
    secrets:
      github-token:
        required: true

permissions:
  contents: read

jobs:
  test-backend:
    name: Backend Tests
    runs-on: ${{ inputs.runner-os }}
    timeout-minutes: 25

    steps:
      - name: Checkout code
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Set up Python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: ${{ inputs.python-version }}

      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8
        with:
          enable-cache: true
          cache-dependency-glob: 'backend/uv.lock'

      - name: Install dependencies
        run: cd backend && uv sync --frozen --all-extras

      - name: Run ruff linter
        run: cd backend && uv run ruff check .

      - name: Run ruff formatter check
        run: cd backend && uv run ruff format --check .

      - name: Run pyright type checking
        run: cd backend && PYTHONPATH=. uv run pyright

      - name: Security tripwire
        if: inputs.security-tripwire-script != ''
        run: bash "${{ inputs.security-tripwire-script }}"

      - name: Run pytest
        run: cd backend && timeout 25m uv run pytest tests/ -v --tb=short

  test-frontend:
    name: Frontend Tests
    runs-on: ${{ inputs.runner-os }}

    steps:
      - name: Checkout code
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Set up Bun (from version-file)
        if: inputs.bun-version == ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version-file: ${{ inputs.bun-version-file }}

      - name: Set up Bun (from explicit override)
        if: inputs.bun-version != ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version: ${{ inputs.bun-version }}

      - name: Install dependencies
        run: cd frontend && bun install --frozen-lockfile

      - name: Run TypeScript type checking
        run: cd frontend && bun run type-check

      - name: Run linter
        run: cd frontend && bun run lint

      - name: Validate translation keys
        if: inputs.enable-translations
        run: cd frontend && bun run validate:translations

      - name: Run tests
        run: cd frontend && bun run test:run

  test-e2e:
    name: E2E Tests
    if: inputs.enable-e2e
    runs-on: ${{ inputs.runner-os }}
    timeout-minutes: 20
    needs: [test-backend, test-frontend]

    steps:
      - name: Checkout code
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Set up Python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: ${{ inputs.python-version }}

      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8
        with:
          enable-cache: true
          cache-dependency-glob: 'backend/uv.lock'

      - name: Install backend dependencies
        run: cd backend && uv sync --frozen --all-extras

      - name: Set up Bun (from version-file)
        if: inputs.bun-version == ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version-file: ${{ inputs.bun-version-file }}

      - name: Set up Bun (from explicit override)
        if: inputs.bun-version != ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version: ${{ inputs.bun-version }}

      - name: Install frontend dependencies
        run: cd frontend && bun install --frozen-lockfile

      - name: Install Playwright browsers
        run: cd frontend && bunx playwright install chromium --with-deps

      - name: Run E2E tests
        run: cd frontend && bun run e2e
        env:
          CI: true
          VULNFORGE_BOOTSTRAP_TOKEN: ${{ inputs.enable-bootstrap-token && 'e2e-ci-test-token' || '' }}

      - name: Upload Playwright report
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: ${{ !cancelled() }}
        with:
          name: playwright-report
          path: frontend/playwright-report/
          retention-days: 14

      - name: Upload test results
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: ${{ !cancelled() }}
        with:
          name: playwright-results
          path: frontend/test-results/
          retention-days: 7

  api-types-freshness:
    name: API Types Freshness
    if: inputs.enable-api-freshness-check
    runs-on: ${{ inputs.runner-os }}
    needs: [test-backend]

    steps:
      - name: Checkout code
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Set up Python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: ${{ inputs.python-version }}

      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8
        with:
          enable-cache: true
          cache-dependency-glob: 'backend/uv.lock'

      - name: Install backend dependencies
        run: cd backend && uv sync --frozen --all-extras

      - name: Set up Bun (from version-file)
        if: inputs.bun-version == ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version-file: ${{ inputs.bun-version-file }}

      - name: Set up Bun (from explicit override)
        if: inputs.bun-version != ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version: ${{ inputs.bun-version }}

      - name: Install frontend dependencies
        run: cd frontend && bun install --frozen-lockfile

      - name: Check API types freshness
        run: cd frontend && bun run check:api-freshness

  docker:
    name: Build and Push Docker Image
    runs-on: ${{ inputs.runner-os }}
    needs: [test-backend, test-frontend, api-types-freshness]
    # api-types-freshness is conditional on inputs.enable-api-freshness-check.
    # When that input is false the job is skipped — and a skipped need would
    # also skip docker without this guard. Allow docker to proceed when
    # api-types-freshness is either successful OR skipped, while still
    # blocking on real test failures.
    if: |
      always()
      && needs.test-backend.result == 'success'
      && needs.test-frontend.result == 'success'
      && (needs.api-types-freshness.result == 'success' || needs.api-types-freshness.result == 'skipped')
    permissions:
      contents: read
      packages: write
      id-token: write
      attestations: write
    outputs:
      digest: ${{ steps.push.outputs.digest }}

    steps:
      - name: Checkout code
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0

      - name: Log in to GitHub Container Registry
        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.github-token }}

      - name: Extract version from tag
        id: version
        run: |
          VERSION=${GITHUB_REF#refs/tags/v}
          MAJOR=$(echo "$VERSION" | cut -d. -f1)
          MINOR=$(echo "$VERSION" | cut -d. -f1-2)
          # Standard semver pre-release: anything with `-` after patch
          # (e.g. v2.27.0-rc1, v2.27.0-beta.1, v3.0.0-alpha).
          # Pre-release tags publish only the exact :VERSION image — they
          # must NOT move :latest, :MAJOR, or :MINOR away from stable.
          if [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
            IS_PRERELEASE=false
          else
            IS_PRERELEASE=true
          fi
          {
            echo "version=$VERSION"
            echo "major=$MAJOR"
            echo "minor=$MINOR"
            echo "is_prerelease=$IS_PRERELEASE"
          } >> "$GITHUB_OUTPUT"

      - name: Read bun version
        id: bun
        run: echo "version=$(cat ${{ inputs.bun-version-file }})" >> "$GITHUB_OUTPUT"

      - name: Compute Docker tags
        id: tags
        run: |
          # Always publish the exact :VERSION tag.
          TAGS="ghcr.io/${{ inputs.image-name }}:${{ steps.version.outputs.version }}"

          # Stable tags only update on non-pre-release builds. Pre-release
          # users (rc/beta/alpha) pin to the exact version; production
          # users on :latest stay on the last stable.
          if [[ "${{ steps.version.outputs.is_prerelease }}" == "false" ]]; then
            TAGS="$TAGS"$'\n'"ghcr.io/${{ inputs.image-name }}:latest"
            TAGS="$TAGS"$'\n'"ghcr.io/${{ inputs.image-name }}:${{ steps.version.outputs.minor }}"
            TAGS="$TAGS"$'\n'"ghcr.io/${{ inputs.image-name }}:${{ steps.version.outputs.major }}"
          fi

          {
            echo "tags<<EOF"
            echo "$TAGS"
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Build and push Docker image
        id: push
        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
        with:
          context: .
          push: true
          tags: ${{ steps.tags.outputs.tags }}
          build-args: |
            BUN_VERSION=${{ steps.bun.outputs.version }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
          platforms: linux/amd64

      - name: Generate artifact attestation
        if: github.event.repository.visibility == 'public'
        continue-on-error: true
        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4
        with:
          subject-name: ghcr.io/${{ inputs.image-name }}
          subject-digest: ${{ steps.push.outputs.digest }}
          push-to-registry: true

  release:
    name: Create GitHub Release
    runs-on: ${{ inputs.runner-os }}
    needs: [docker]
    # The docker job uses `if: always() && ...` to handle the
    # api-types-freshness-skipped case. That marks docker as a
    # conditional job, which causes downstream `needs:` evaluation to
    # treat docker's "success" differently from an unconditional job.
    # Use `always() &&` here too so this if: always evaluates, and
    # gate explicitly on docker's actual result.
    if: always() && needs.docker.result == 'success'
    permissions:
      contents: write
      packages: read

    steps:
      - name: Checkout code
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          fetch-depth: 0

      - name: Extract version from tag
        id: version
        run: |
          VERSION=${GITHUB_REF#refs/tags/v}
          echo "version=$VERSION" >> "$GITHUB_OUTPUT"

      - name: Extract changelog for this version
        id: changelog
        run: |
          VERSION=${{ steps.version.outputs.version }}
          CHANGELOG=$(awk -v ver="$VERSION" '
            /^## \[.*\]/ {
              if (found) exit
              if ($0 ~ "\\[" ver "\\]") found=1
              next
            }
            found { print }
          ' CHANGELOG.md)
          echo "$CHANGELOG" > release_notes.md

      - name: Check if pre-release
        id: prerelease
        run: |
          VERSION=${{ steps.version.outputs.version }}
          if [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
            echo "prerelease=false" >> "$GITHUB_OUTPUT"
          else
            echo "prerelease=true" >> "$GITHUB_OUTPUT"
          fi

      - name: Create GitHub Release
        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0
        env:
          GITHUB_TOKEN: ${{ secrets.github-token }}
        with:
          name: ${{ inputs.release-name-prefix }}${{ steps.version.outputs.version }}
          body_path: release_notes.md
          draft: false
          prerelease: ${{ steps.prerelease.outputs.prerelease }}
          generate_release_notes: true