docs.yml

---
#   Copyright 2026 Google LLC
#
#   Licensed under the Apache License, Version 2.0 (the "License");
#   you may not use this file except in compliance with the License.
#   You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#   Unless required by applicable law or agreed to in writing, software
#   distributed under the License is distributed on an "AS IS" BASIS,
#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#   See the License for the specific language governing permissions and
#   limitations under the License.

name: Docs Build and Deploy

on:
  workflow_dispatch:

  push:
    branches:
      - main
      - "release/**"
  pull_request:
    branches:
      - main
      - "release/**"
    paths:
      - ".github/workflows/docs.yml"
      - "requirements-docs.txt"
      - "mkdocs.yml"
      - "main.py"
      - "hooks.py"
      - "docs/**"
      - "source/**"

jobs:
  lint:
    runs-on: ubuntu-latest
    # Don't run this workflow if this is a release branch creation event
    # (event.before SHA is all zeros)
    if: >-
      !(github.event_name == 'push' &&
        startsWith(github.ref, 'refs/heads/release/') &&
        github.event.before == '0000000000000000000000000000000000000000')
    steps:
      - name: Checkout Code
        uses: actions/checkout@v5
        with:
          fetch-depth: 0

      - uses: ./.github/actions/setup-build-env

      - name: Lint YAML files
        run: uv run yamllint -c .github/linters/.yamllint.yml .

      - name: Check for changed files in source
        id: source_files_changed
        uses: tj-actions/changed-files@v46
        with:
          files: source/**

      - name: Lint source schemas
        if: steps.source_files_changed.outputs.any_changed == 'true' || github.event_name == 'workflow_dispatch'
        run: ucp-schema lint source/

  build_and_verify_main:
    needs: lint
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' || github.event.pull_request.base.ref == 'main'
    permissions:
      contents: read
      pages: read
    steps:
      - name: Checkout Code
        uses: actions/checkout@v5
        with:
          fetch-depth: 0

      - name: Configure Git Credentials
        run: |
          git config --global user.name github-actions[bot]
          git config --global user.email 41898282+github-actions[bot]@users.noreply.github.com

      - uses: ./.github/actions/setup-build-env

      - uses: ./.github/actions/configure-site-url

      - name: Build and Verify Documentation Site (Main/PR)
        run: |
          bash scripts/build_local.sh --main-only
          uv run python scripts/check_links.py local_preview

  build_and_verify_release:
    needs: lint
    runs-on: ubuntu-latest
    if: >-
      startsWith(github.ref, 'refs/heads/release/') ||
      startsWith(github.event.pull_request.base.ref, 'release/')
    permissions:
      contents: read
      pages: read
    steps:
      - name: Checkout Code
        uses: actions/checkout@v5
        with:
          fetch-depth: 0

      - name: Configure Git Credentials
        run: |
          git config --global user.name github-actions[bot]
          git config --global user.email 41898282+github-actions[bot]@users.noreply.github.com

      - uses: ./.github/actions/setup-build-env

      - uses: ./.github/actions/configure-site-url

      - name: Build and Verify Specification Docs (Release Branches)
        run: |
          export DOCS_MODE=spec
          uv run mkdocs build --strict
          uv run python scripts/check_links.py site

  deploy_main:
    needs: build_and_verify_main
    runs-on: ubuntu-latest
    if: contains(fromJson('["push", "workflow_dispatch"]'), github.event_name) && github.ref == 'refs/heads/main'
    permissions:
      contents: write
      pages: read
    steps:
      - name: Checkout Code
        uses: actions/checkout@v5
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fetch-depth: 0

      - name: Configure Git Credentials
        run: |
          git config --global user.name github-actions[bot]
          git config --global user.email 41898282+github-actions[bot]@users.noreply.github.com

      - uses: ./.github/actions/setup-build-env

      - uses: ./.github/actions/configure-site-url

      - name: Deploy development version from main branch
        run: |
          export DOCS_MODE=spec
          uv run mike deploy --push draft

          export DOCS_MODE=root
          uv run mkdocs build --strict

          # Checkout gh-pages into a separate directory to avoid overwriting the workspace
          # and causing GitHub Actions post-run hooks to fail (as they need .github/actions)
          git clone --branch gh-pages "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" gh-pages-branch
          cd gh-pages-branch

          # Remove existing root files except versions and git metadata
          git ls-files | grep -vE "^(\.nojekyll|draft|latest|[0-9]{4}-[0-9]{2}-[0-9]{2}|versions\.json|\.git)" | xargs -r rm -f
          find . -maxdepth 1 -type d -empty -not -path "./.git*" -delete

          # Copy build artifacts to root
          cp -r ../site/* .
          rm -rf ../site

          # Add redirects for all specification files
          rm -rf specification
          ln -s latest/specification specification

          # Commit and push
          git add .
          git commit -m "Deploy root site from main" --allow-empty
          git push origin gh-pages

  deploy_release:
    needs: build_and_verify_release
    runs-on: ubuntu-latest
    if: contains(fromJson('["push", "workflow_dispatch"]'), github.event_name) && startsWith(github.ref, 'refs/heads/release/')
    permissions:
      contents: write
      pages: read
    steps:
      - name: Checkout Code
        uses: actions/checkout@v5
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fetch-depth: 0

      - name: Configure Git Credentials
        run: |
          git config --global user.name github-actions[bot]
          git config --global user.email 41898282+github-actions[bot]@users.noreply.github.com

      - uses: ./.github/actions/setup-build-env

      - uses: ./.github/actions/configure-site-url

      - name: Deploy release version
        run: |
          export DOCS_MODE=spec
          VERSION_NAME=${GITHUB_REF#refs/heads/release/}
          git fetch origin "+refs/heads/release/*:refs/remotes/origin/release/*"
          LATEST_VERSION=$(git branch -r --list "origin/release/*" | sed 's|origin/release/||' | sort -V | tail -n 1 | tr -d ' ')

          if [ "$VERSION_NAME" = "$LATEST_VERSION" ]; then
            uv run mike deploy --push --update-aliases "$VERSION_NAME" latest
          else
            uv run mike deploy --push "$VERSION_NAME"
          fi

  create_release:
    needs: deploy_release
    runs-on: ubuntu-latest
    if: contains(fromJson('["push", "workflow_dispatch"]'), github.event_name) && startsWith(github.ref, 'refs/heads/release/')
    permissions:
      contents: write
    steps:
      - name: Checkout Code
        uses: actions/checkout@v5
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fetch-depth: 0

      - name: Create GitHub Release and Tag
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          VERSION_DATE=${GITHUB_REF#refs/heads/release/}
          TAG_NAME="v$VERSION_DATE"

          gh release create "$TAG_NAME" \
            --title "Release $TAG_NAME" \
            --generate-notes \
            --target "$GITHUB_REF_NAME" \
            || echo "Release $TAG_NAME already exists, skipping creation."