deploy-site.yml

# Workflow for deploying versioned documentation to GitHub Pages.
# Site content (src/site/, pom.xml) lives in THIS repo.
# Java source code is checked out from the monorepo (github/copilot-sdk) at a release tag.
name: Deploy Documentation

on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to build in tag format (e.g., java/v1.0.1-java.0). The java/v prefix is stripped to form the site directory name.'
        type: string
        required: true
      publish_as_latest:
        description: 'Also publish as /latest/?'
        type: boolean
        default: true
      monorepo_tag:
        description: 'Tag in github/copilot-sdk monorepo (e.g., java/v1.0.1-java.0)'
        type: string
        required: true

permissions:
  contents: write
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      # 0. Validate inputs
      - name: Validate inputs
        run: |
          VERSION="${{ inputs.version }}"
          if [[ -z "${VERSION}" ]]; then
            echo "::error::version input is required"
            exit 1
          fi
          if [[ "${VERSION}" == *"../"* ]]; then
            echo "::error::version must not contain '../'"
            exit 1
          fi
          TAG="${{ inputs.monorepo_tag }}"
          if [[ "${TAG}" != java/v* ]]; then
            echo "::error::monorepo_tag must start with 'java/v' (got: '${TAG}')"
            exit 1
          fi

      # 1. Checkout this (standalone) repo — has src/site/, pom.xml, templates
      - name: Checkout standalone repo
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      # 2. Checkout the monorepo at the release tag (for Java source code)
      - name: Checkout monorepo at release tag
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          repository: github/copilot-sdk
          ref: ${{ inputs.monorepo_tag }}
          path: monorepo

      # 3. Set up JDK
      - name: Set up JDK 25
        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5
        with:
          java-version: '25'
          distribution: 'microsoft'
          cache: 'maven'

      # 4. Compile monorepo Java source (needed for javadoc, SpotBugs, etc.)
      - name: Compile monorepo Java source
        working-directory: monorepo/java
        run: |
          echo "Compiling Java source from tag ${{ inputs.monorepo_tag }}"
          mvn clean compile test -DskipTests=false -Dcheckstyle.skip=true -B

      # 5. Build the Maven Site using THIS repo's pom.xml + src/site/
      - name: Build documentation site
        run: |
          echo "Building site for version ${{ inputs.version }}"
          mvn site -Dsite.version=${{ inputs.version }} -B

      # 6. Prepare gh-pages deployment directory
      - name: Prepare gh-pages directory
        run: |
          # Try to clone existing gh-pages branch (shallow)
          git clone --depth 1 --branch gh-pages \
            "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" \
            site 2>/dev/null || {
            echo "No gh-pages branch exists yet, creating fresh"
            mkdir -p site
            cd site
            git init
            git checkout -b gh-pages
          }

      # 7. Copy generated site to version directory
      - name: Deploy version documentation
        run: |
          VERSION="${{ inputs.version }}"
          echo "Deploying documentation for version ${VERSION}"

          rm -rf "site/${VERSION}"
          mkdir -p "site/${VERSION}"
          cp -r target/site/* "site/${VERSION}/"

          # Also publish as /latest/ if requested
          if [[ "${{ inputs.publish_as_latest }}" == "true" ]]; then
            rm -rf "site/latest"
            mkdir -p "site/latest"
            cp -r target/site/* "site/latest/"
          fi

      # 8. Copy version index page from templates
      - name: Copy version index page
        run: |
          cp .github/templates/index.html site/index.html
          cp .github/templates/styles.css site/styles.css

      # 9. Update version list based on directories present in gh-pages
      - name: Update version list from deployed directories
        run: |
          cd site

          MONOREPO_URL="https://github.com/github/copilot-sdk"
          CURRENT_VERSION="${{ inputs.version }}"

          # Community releases: versions that existed before the monorepo era.
          # These are all versions that are NOT the current deploy version.
          # They go into the "Community releases" collapsible section.
          COMMUNITY_VERSIONS="1.0.9 1.0.8 1.0.7 1.0.6 1.0.5 1.0.4 1.0.3 1.0.2 1.0.1 1.0.0-beta-java.4 1.0.0-beta-java.3 1.0.0-beta-java.2 1.0.0-beta-java.1 1.0.0-beta-10-java.0 1.0.0-beta-8-java.0 0.3.0-java.2"
          STANDALONE_URL="https://github.com/github/copilot-sdk-java"

          # Current version (the one just deployed)
          CURRENT_HTML='<li class="latest-version"><span class="version-name">Version '"${CURRENT_VERSION}"'</span><span class="version-links"><a href="./'"${CURRENT_VERSION}"'/" class="doc-link">documentation ↗</a><a href="'"${MONOREPO_URL}"'/releases/tag/java/v'"${CURRENT_VERSION}"'" class="release-link">release notes ↗</a><span class="badge latest">latest</span></span></li>'

          # Older releases: previous monorepo releases (all version dirs that
          # are NOT the current version and NOT in the community list)
          OLDER_HTML=""
          ALL_VERSIONS=$(ls -d */ 2>/dev/null | sed 's|/||' | grep -E '^[0-9]+\.[0-9]+' | sort -Vr || true)
          for v in $ALL_VERSIONS; do
            # Skip current version
            [[ "$v" == "$CURRENT_VERSION" ]] && continue
            # Skip community versions
            echo "$COMMUNITY_VERSIONS" | tr ' ' '\n' | grep -qx "$v" && continue
            # Skip snapshot/latest dirs
            [[ "$v" == "snapshot" || "$v" == "latest" ]] && continue
            RELEASE_URL="${MONOREPO_URL}/releases/tag/java/v${v}"
            OLDER_HTML+='<li><span>'"$v"'</span><span class="older-links"><a href="./'"$v"'/" class="doc-link">documentation ↗</a><a href="'"$RELEASE_URL"'" class="release-link">release notes ↗</a></span></li>'
          done

          # Community releases
          COMMUNITY_HTML=""
          for v in $COMMUNITY_VERSIONS; do
            if [ -d "$v" ]; then
              RELEASE_URL="${STANDALONE_URL}/releases/tag/v${v}"
              COMMUNITY_HTML+='<li><span>'"$v"'</span><span class="older-links"><a href="./'"$v"'/" class="doc-link">documentation ↗</a><a href="'"$RELEASE_URL"'" class="release-link">release notes ↗</a></span></li>'
            fi
          done

          sed -i "s|<!-- CURRENT_VERSION_PLACEHOLDER -->|$CURRENT_HTML|" index.html
          sed -i "s|<!-- OLDER_VERSIONS_PLACEHOLDER -->|$OLDER_HTML|" index.html
          sed -i "s|<!-- COMMUNITY_VERSIONS_PLACEHOLDER -->|$COMMUNITY_HTML|" index.html

      # 10. Overlay custom JaCoCo CSS
      - name: Overlay custom JaCoCo CSS
        run: |
          cd site
          JACOCO_CSS="../src/site/jacoco-resources/report.css"
          if [ -f "${JACOCO_CSS}" ]; then
            for dir in */jacoco/jacoco-resources; do
              if [ -d "$dir" ]; then
                cp "${JACOCO_CSS}" "$dir/report.css"
                echo "Overlaid JaCoCo CSS in $dir"
              fi
            done
          fi

      # 11. Push to gh-pages
      - name: Deploy to GitHub Pages
        run: |
          cd site
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

          git remote set-url origin "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" 2>/dev/null || \
            git remote add origin "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git"

          git add -A

          COMMIT_MSG="Deploy documentation: ${{ inputs.version }} (from ${{ inputs.monorepo_tag }})"
          git diff --staged --quiet || git commit -m "$COMMIT_MSG"

          git push origin gh-pages --force
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Setup Pages
        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0

      - name: Upload artifact
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: 'site'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0