publish-spec.yml

name: Publish Specification

on:
  pull_request:
    types:
      - opened
      - synchronize
      - reopened
      - ready_for_review
      - closed
    paths:
      - .github/workflows/publish-spec.yml
      - pyproject.toml
      - uv.lock
      - specification/ai-catalog.md
      - specification/respec-config.json
      - tools/build_spec.py
      - tools/build_spec_preview.py
      - tools/update_gh_pages.py
  push:
    branches:
      - main
    paths:
      - .github/workflows/publish-spec.yml
      - pyproject.toml
      - uv.lock
      - specification/ai-catalog.md
      - specification/respec-config.json
      - tools/build_spec.py
      - tools/build_spec_preview.py
      - tools/update_gh_pages.py
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: spec-pages-${{ github.event_name }}-${{ github.event.pull_request.number || github.ref_name }}
  cancel-in-progress: true

jobs:
  build:
    if: github.event_name != 'pull_request' || github.event.action != 'closed'
    runs-on: ubuntu-latest
    permissions:
      contents: read

    steps:
      - name: Check out repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4

      - name: Set up uv
        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
        with:
          enable-cache: true
          cache-dependency-glob: uv.lock

      - name: Build specification site
        run: |
          uv run --python 3.12 --locked python tools/build_spec.py specification/ai-catalog.md dist/index.html --config specification/respec-config.json

  publish-root:
    if: |
      (github.event_name == 'push' && github.ref == 'refs/heads/main') ||
      (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')
    needs: build
    runs-on: ubuntu-latest
    concurrency:
      group: gh-pages-write
      cancel-in-progress: false
    permissions:
      contents: write

    steps:
      - name: Check out repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4

      - name: Set up uv
        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
        with:
          enable-cache: true
          cache-dependency-glob: uv.lock

      - name: Build canonical specification site
        run: |
          uv run --python 3.12 --locked python tools/build_spec.py specification/ai-catalog.md .site/root/index.html --config specification/respec-config.json

      - name: Publish canonical site to gh-pages
        run: |
          python3 tools/update_gh_pages.py root \
            --source-dir .site/root \
            --cname ai-catalog.io \
            --remote-url "https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.git" \
            --commit-message "Publish specification site from main"

  publish-pr-preview:
    if: |
      github.event_name == 'pull_request' &&
      github.event.action != 'closed' &&
      github.event.pull_request.head.repo.full_name == github.repository
    needs: build
    runs-on: ubuntu-latest
    concurrency:
      group: gh-pages-write
      cancel-in-progress: false
    permissions:
      contents: write
      issues: write
      pull-requests: write

    steps:
      - name: Check out pull request merge ref
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4

      - name: Set up uv
        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
        with:
          enable-cache: true
          cache-dependency-glob: uv.lock

      - name: Fetch base and head history
        env:
          BASE_REF: ${{ github.event.pull_request.base.ref }}
          HEAD_REF: ${{ github.event.pull_request.head.ref }}
        run: |
          git fetch --no-tags origin "$BASE_REF" "$HEAD_REF"

      - name: Resolve preview revisions
        id: preview-revisions
        env:
          BASE_REF: ${{ github.event.pull_request.base.ref }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: |
          base_sha=$(git rev-parse "origin/${BASE_REF}")
          if ! git cat-file -e "${HEAD_SHA}^{commit}"; then
            git fetch --no-tags origin "${HEAD_SHA}"
          fi
          echo "base_sha=${base_sha}" >> "$GITHUB_OUTPUT"
          echo "head_sha=${HEAD_SHA}" >> "$GITHUB_OUTPUT"

      - name: Build rendered PR preview site
        run: |
          uv run --python 3.12 --locked python tools/build_spec_preview.py \
            --base-sha "${{ steps.preview-revisions.outputs.base_sha }}" \
            --head-sha "${{ steps.preview-revisions.outputs.head_sha }}" \
            --base-branch "${{ github.event.pull_request.base.ref }}" \
            --head-branch "${{ github.event.pull_request.head.ref }}" \
            --pr-number "${{ github.event.pull_request.number }}" \
            --output-dir ".site/pr/${{ github.event.pull_request.number }}"

      - name: Publish PR preview to gh-pages
        run: |
          python3 tools/update_gh_pages.py preview \
            --source-dir ".site/pr/${{ github.event.pull_request.number }}" \
            --pr-number "${{ github.event.pull_request.number }}" \
            --remote-url "https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.git" \
            --commit-message "Publish specification preview for PR #${{ github.event.pull_request.number }}"

      - name: Comment preview URL on pull request
        env:
          GH_TOKEN: ${{ github.token }}
          PREVIEW_URL: https://ai-catalog.io/pr/${{ github.event.pull_request.number }}/
        run: |
          marker='<!-- ai-catalog-preview-url -->'
          body=$(cat <<EOF
          ${marker}
          Preview: ${PREVIEW_URL}

          This comment is updated automatically while the pull request preview is available.
          EOF
          )
          gh pr comment "${{ github.event.pull_request.number }}" \
            --repo "${{ github.repository }}" \
            --edit-last \
            --create-if-none \
            --body "$body"

  cleanup-pr-preview:
    if: |
      github.event_name == 'pull_request' &&
      github.event.action == 'closed' &&
      github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    concurrency:
      group: gh-pages-write
      cancel-in-progress: false
    permissions:
      contents: write
      issues: write
      pull-requests: write

    steps:
      - name: Check out repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4

      - name: Remove PR preview from gh-pages
        run: |
          python3 tools/update_gh_pages.py cleanup \
            --pr-number "${{ github.event.pull_request.number }}" \
            --remote-url "https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.git" \
            --commit-message "Remove specification preview for PR #${{ github.event.pull_request.number }}"

      - name: Update preview comment on pull request close
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          marker='<!-- ai-catalog-preview-url -->'
          body=$(cat <<EOF
          ${marker}
          Preview unavailable.

          The pull request preview was removed because this pull request is closed.
          EOF
          )
          gh pr comment "${{ github.event.pull_request.number }}" \
            --repo "${{ github.repository }}" \
            --edit-last \
            --create-if-none \
            --body "$body"