docs-deploy.yml

name: docs-deploy

on:
  push:
    tags:
      - "v*.*.*"
  workflow_dispatch:
    inputs:
      version:
        description: "mike version alias (e.g. 0.3 or latest)"
        required: true
        default: "latest"

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - name: Install uv
        uses: astral-sh/setup-uv@v7
        with:
          python-version: "3.13"

      # arduino/setup-protoc@v3 has an unfixed bug ("unable to get latest
      # version", arduino/setup-protoc#108) that intermittently breaks CI
      # even with an explicit version pin. Install protoc directly from
      # the upstream release archive instead — same pattern as docs.yml.
      - name: Install protoc
        run: |
          set -euo pipefail
          PROTOC_VERSION=27.3
          curl -fsSL -o /tmp/protoc.zip \
            "https://github.com/protocolbuffers/protobuf/releases/download/v${PROTOC_VERSION}/protoc-${PROTOC_VERSION}-linux-x86_64.zip"
          sudo unzip -q -o /tmp/protoc.zip -d /usr/local
          sudo chmod +x /usr/local/bin/protoc
          protoc --version

      - name: Set up Go
        uses: actions/setup-go@v7
        with:
          go-version-file: packages/fathom-go/go.mod

      - name: Install protoc-gen-doc
        run: go install github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc@v1.5.1

      - name: Install Node
        uses: actions/setup-node@v7
        with:
          node-version: "20"

      - name: Install pnpm
        uses: pnpm/action-setup@v6
        with:
          version: 9

      - name: Install Python deps
        run: uv sync --extra docs --extra server --extra mcp --extra attestation

      - name: Generate everything
        run: |
          make docs-gen
          make docs-gen-foreign

      - name: Configure git for mike
        run: |
          git config user.name "docs-bot"
          git config user.email "docs-bot@users.noreply.github.com"

      - name: Resolve version label
        id: label
        env:
          EVENT_NAME: ${{ github.event_name }}
          DISPATCH_VERSION: ${{ inputs.version }}
        run: |
          set -euo pipefail
          if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
            echo "version=$DISPATCH_VERSION" >> "$GITHUB_OUTPUT"
            echo "alias=" >> "$GITHUB_OUTPUT"
          else
            TAG="${GITHUB_REF##refs/tags/}"
            VER="${TAG#v}"
            MM="$(echo "$VER" | awk -F. '{print $1"."$2}')"
            echo "version=${MM}" >> "$GITHUB_OUTPUT"
            echo "alias=latest" >> "$GITHUB_OUTPUT"
          fi

      # ``mike deploy --update-aliases X Y`` aborts with "alias 'Y' already
      # specified as a version" when Y was previously deployed as a real
      # version. Retire that collision before deploying so the workflow is
      # idempotent across historical gh-pages states.
      - name: Retire stale alias-as-version (if any)
        if: steps.label.outputs.alias != ''
        env:
          ALIAS: ${{ steps.label.outputs.alias }}
        run: |
          set -euo pipefail
          if uv run mike list --json 2>/dev/null \
              | python -c "import json,os,sys; want=os.environ['ALIAS']; sys.exit(0 if any(e.get('version')==want for e in json.load(sys.stdin)) else 1)"; then
            echo "Alias '$ALIAS' is registered as a version; deleting before redeploy."
            uv run mike delete --push "$ALIAS"
          else
            echo "No stale '$ALIAS' version to retire."
          fi

      - name: Deploy via mike
        env:
          VERSION: ${{ steps.label.outputs.version }}
          ALIAS: ${{ steps.label.outputs.alias }}
        run: |
          set -euo pipefail
          if [ -n "$ALIAS" ]; then
            uv run mike deploy --push --update-aliases "$VERSION" "$ALIAS"
            uv run mike set-default --push "$ALIAS"
          else
            uv run mike deploy --push "$VERSION"
            uv run mike set-default --push "$VERSION"
          fi