RC Previews

name: Deploy RC preview to GitHub Pages

on:
  push:
    tags:
      - "v*-rc.*"
  workflow_dispatch:

permissions:
  contents: write


jobs:
  deploy-rc-pages:
    if: ${{ env.ENABLE_DEPLOY == 'true' && env.CI_PROVIDER == 'github' && env.ACT != 'true' }}
    runs-on: ubuntu-latest

    steps:
      - name: Checkout (tag)
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Ensure tag commit is on release-candidate
        run: |
          set -euo pipefail
          git fetch origin release-candidate:refs/remotes/origin/release-candidate
          if ! git merge-base --is-ancestor "${GITHUB_SHA}" "origin/release-candidate"; then
            echo "ERROR: Tagged commit ${GITHUB_SHA} is not on release-candidate. Refusing RC deploy."
            exit 1
          fi

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.13"
          cache: "pip"
          cache-dependency-path: mkdocs/requirements.txt

      - name: Install dependencies
        run: |
          set -euo pipefail
          pip install -r mkdocs/requirements.txt

      - name: Build (MKDOCS_STRICT)
        run: |
          set -euo pipefail

          MKDOCS_STRICT="${MKDOCS_STRICT:-true}"
          STRICT_FLAG=""
          if [ "${MKDOCS_STRICT}" = "true" ]; then
            STRICT_FLAG="--strict"
          fi

          OFFLINE=true mkdocs build ${STRICT_FLAG} -f mkdocs/mkdocs.yml -d site_build

      - name: Checkout gh-pages branch
        run: |
          set -euo pipefail
          git fetch origin gh-pages:gh-pages || true
          if git show-ref --verify --quiet refs/heads/gh-pages; then
            git switch gh-pages
          else
            git switch --orphan gh-pages
            rm -rf ./*
            git config user.name "github-actions[bot]"
            git config user.email "github-actions[bot]@users.noreply.github.com"
            git commit --allow-empty -m "Initialize gh-pages"
          fi

      - name: Publish RC preview under /rc/<tag>/
        run: |
          set -euo pipefail
          REF="${{ github.ref_name }}"
          mkdir -p "rc/${REF}"
          rm -rf "rc/${REF:?}/"* || true
          cp -a ../site_build/. "rc/${REF}/"

          mkdir -p rc
          if [ ! -f rc/index.html ]; then
            cat > rc/index.html << 'EOF'
<!doctype html><meta charset="utf-8"><title>RC Previews</title>
<h1>RC Previews</h1><p>Browse rc/&lt;tag&gt;/</p>
EOF
          fi

          git add -A
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git commit -m "Deploy RC preview ${REF}" || echo "No changes to commit"
          git push origin gh-pages