reference-docs.yaml

# Generates Kubernetes API reference docs from agentgateway/agentgateway.
# Version configuration is read directly from hugo.yaml (params.sections.standalone.versions).
# Released versions resolve the latest matching tag dynamically via tagPrefix derived from the
# version string (e.g. 1.0.x -> v1.0.*). The "main" linkVersion uses the main branch directly.
#
# workflow_dispatch inputs:
#   doc_version: a specific version (e.g. 1.0.x), or "all" to run for every version in hugo.yaml
name: Generate API reference docs for agentgateway

on:
  release:
    types: [created]
  schedule:
    # Nightly at 06:00 UTC: regenerate docs for every version (incl. main) so docs don't drift from code.
    - cron: '0 6 * * *'
  workflow_dispatch:
    inputs:
      doc_version:
        description: 'Doc version to generate (must match a version in hugo.yaml), e.g. 1.0.x, or "all"'
        required: true
        default: '1.0.x'

# Queue overlapping runs (e.g. nightly cron + a manual dispatch) so they don't force-push the same PR branches concurrently.
concurrency:
  group: reference-docs
  cancel-in-progress: false

# create-pull-request pushes a branch and opens a PR, so the GITHUB_TOKEN needs write on both.
# Without this block the token is read-only and the push fails with a 403.
# Note: this still requires "Allow GitHub Actions to create and approve pull requests"
# to be enabled in repo Settings -> Actions -> General (or a CREATE_PR_TOKEN PAT).
permissions:
  contents: write
  pull-requests: write

jobs:
  setup:
    name: Setup and validate
    runs-on: ubuntu-22.04
    outputs:
      matrix: ${{ steps.build_matrix.outputs.matrix }}
    steps:
      - name: Checkout website repo
        uses: actions/checkout@v4
        with:
          path: website
          fetch-depth: 1

      - name: Build version matrix
        id: build_matrix
        env:
          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
        run: |
          if [[ "${{ github.event_name }}" == "release" ]]; then
            input_version="1.0.x"
          elif [[ "${{ github.event_name }}" == "schedule" ]]; then
            # Scheduled events carry no inputs; regenerate every version.
            input_version="all"
          else
            input_version="${{ inputs.doc_version }}"
          fi

          # Read all versions from hugo.yaml
          all_versions=$(python3 -c "
          import yaml, json, sys
          with open('website/hugo.yaml') as f:
              cfg = yaml.safe_load(f)
          versions = cfg['params']['sections']['standalone']['versions']
          print(json.dumps(versions))
          ")

          # Determine which versions to process
          if [[ "$input_version" == "all" ]]; then
            target_versions="$all_versions"
          else
            target_versions=$(python3 -c "
          import json, sys
          versions = json.loads(sys.argv[1])
          entry = next((v for v in versions if v['version'] == sys.argv[2]), None)
          if not entry:
              valid = [v['version'] for v in versions]
              print(f'Error: version {sys.argv[2]} not found in hugo.yaml. Valid versions: {valid}', file=sys.stderr)
              sys.exit(1)
          print(json.dumps([entry]))
            " "$all_versions" "$input_version")
          fi

          # Resolve the git ref for each version and build the matrix
          matrix_items='[]'
          while IFS= read -r entry; do
            doc_version=$(echo "$entry" | jq -r '.version')
            link_version=$(echo "$entry" | jq -r '.linkVersion')

            if [[ "$link_version" == "main" ]]; then
              echo "Checking branch: main"
              if ! git ls-remote --heads https://github.com/agentgateway/agentgateway.git refs/heads/main | grep -q main; then
                echo "Error: main branch not found in agentgateway/agentgateway"
                exit 1
              fi
              ref="main"
            else
              TAG_PREFIX=$(echo "$doc_version" | sed 's/\.[^.]*$/\./' | sed 's/^/v/')
              echo "Resolving latest tag with prefix ${TAG_PREFIX}..."
              ref=$(gh api repos/agentgateway/agentgateway/tags --paginate \
                --jq '.[].name' | grep "^${TAG_PREFIX}" | sort -V | tail -1)
              if [[ -z "$ref" ]]; then
                echo "Error: no tags found matching prefix ${TAG_PREFIX} in agentgateway/agentgateway"
                exit 1
              fi
              echo "Resolved ${doc_version} (${link_version}) -> ${ref}"
            fi

            item=$(jq -n \
              --arg dv "$doc_version" \
              --arg lv "$link_version" \
              --arg r "$ref" \
              '{doc_version: $dv, link_version: $lv, ref: $r}')
            matrix_items=$(echo "$matrix_items" | jq --argjson item "$item" '. + [$item]')
          done < <(echo "$target_versions" | jq -c '.[]')

          matrix=$(echo "$matrix_items" | jq -c '{include: .}')
          echo "matrix=${matrix}" >> $GITHUB_OUTPUT
          echo "Matrix: $matrix"

  api-docs:
    name: Generate API docs (${{ matrix.link_version }})
    runs-on: ubuntu-22.04
    needs: setup
    strategy:
      matrix: ${{ fromJson(needs.setup.outputs.matrix) }}
      fail-fast: false
    env:
      GOTOOLCHAIN: auto
    steps:
      - name: Checkout website repo
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.GH_TOKEN }}
          path: website
          fetch-depth: 0

      - name: Checkout agentgateway source repository
        uses: actions/checkout@v4
        with:
          repository: agentgateway/agentgateway
          token: ${{ secrets.GH_TOKEN }}
          path: agentgateway
          ref: ${{ matrix.ref }}

      - name: Setup Go for docs generation
        uses: actions/setup-go@v6
        with:
          go-version-file: agentgateway/go.mod
          cache: false

      - name: Setup Hugo for rendered docs extraction
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: '0.160.1'
          extended: true

      - name: Install website dependencies
        working-directory: website
        run: npm ci

      - name: Generate agentgateway API docs
        run: |
          pushd website || exit 1

          LINK_VERSION="${{ matrix.link_version }}"
          API_FILE="api-${LINK_VERSION}.md"

          # API types live in agentgateway controller/api/v1alpha1/agentgateway/
          echo "Generating agentgateway API docs from controller/api/v1alpha1/agentgateway/"
          go run github.com/elastic/crd-ref-docs@latest \
            --source-path="$PWD/../agentgateway/controller/api/v1alpha1/agentgateway/" \
            --renderer=markdown \
            --output-path ./ \
            --max-depth=100 \
            --config=scripts/crd-ref-docs-config.yaml

          if [ ! -f "./out.md" ]; then
            echo "Error: API docs generation failed - out.md not found"
            exit 1
          fi

          TARGET_DIR="assets/agw-docs/pages/reference/api"
          mkdir -p "$TARGET_DIR"
          TARGET_FILE="${TARGET_DIR}/${API_FILE}"

          echo "Processing API docs -> ${TARGET_FILE}"

          # Remove first 3 lines and fix common artifacts
          tail -n +4 "./out.md" | \
            sed 's/Required: {}/Required/g; s/Optional: {}/Optional/g; /^# API Reference$/,/^$/d' \
            > "$TARGET_FILE"

          # Simplify complex struct types
          sed -i.bak -E 's/_Underlying type:_ _\[?struct\{[^}]*\}[]\)]*(\\([^)]+\\))?_/_Underlying type:_ _struct_/g' "$TARGET_FILE"
          # Drop the broken intra-page anchor crd-ref-docs emits for map-alias
          # underlying types (e.g. `map[string]CELExpression` -> #map[string]celexpression,
          # which never gets a heading), keeping the readable type text.
          sed -i.bak -E 's/_Underlying type:_ _\[(map\[[^]]*\][^]]*)\]\(#[^)]*\)_/_Underlying type:_ _\1_/g' "$TARGET_FILE"
          rm -f "$TARGET_FILE.bak"

          rm "./out.md"
          echo "API docs generated successfully at $TARGET_FILE"

          popd || exit 1

      - name: Generate shared types documentation
        run: |
          LINK_VERSION="${{ matrix.link_version }}"
          TARGET_FILE="website/assets/agw-docs/pages/reference/api/api-${LINK_VERSION}.md"
          SHARED_DIR="agentgateway/controller/api/v1alpha1/shared"
          AGENTGATEWAY_SOURCE_DIR="agentgateway/controller/api/v1alpha1/agentgateway"
          if [ -f "$TARGET_FILE" ]; then
            echo "Generating shared types documentation for api-${LINK_VERSION}.md..."
            python3 website/scripts/generate-shared-types.py \
              "$SHARED_DIR" \
              "$TARGET_FILE" \
              "$AGENTGATEWAY_SOURCE_DIR"
          else
            echo "API doc file not found - skipping shared types"
          fi

      - name: Generate Helm and metrics docs
        run: |
          LINK_VERSION="${{ matrix.link_version }}" \
          WEBSITE_DIR="website" \
          KGATEWAY_DIR="agentgateway/controller" \
          python3 website/scripts/generate-ref-docs.py

      - name: Generate agctl CLI reference
        run: |
          LINK_VERSION="${{ matrix.link_version }}" \
          WEBSITE_DIR="website" \
          KGATEWAY_DIR="agentgateway" \
          python3 website/scripts/generate-agctl-ref.py

      - name: Build rendered docs for kubespec index
        working-directory: website
        run: hugo --config hugo.yaml

      - name: Generate kubespec widget HTMLs
        run: |
          LINK_VERSION="${{ matrix.link_version }}"
          CRD_DIR="${GITHUB_WORKSPACE}/agentgateway/controller/install/helm/agentgateway-crds/templates"
          DOCS_KEY_FILE="${RUNNER_TEMP}/${LINK_VERSION}-keys.json"
          RENDERED_DOCS_DIR="${GITHUB_WORKSPACE}/website/public/docs/kubernetes/${LINK_VERSION}"
          TARGET_DIR="${GITHUB_WORKSPACE}/website/assets/agw-docs/pages/reference/api/${LINK_VERSION}"
          mkdir -p "$TARGET_DIR"

          python3 website/scripts/extract_rendered_yaml.py \
            --input-dir "$RENDERED_DOCS_DIR" \
            --agentgateway-keys \
            > "$DOCS_KEY_FILE"

          echo "Generating interactive kubespec widget HTMLs from CRD YAMLs..."
          for crd in "$CRD_DIR"/agentgateway.dev_*.yaml; do
            basename="$(basename "$crd")"
            echo "  Rendering ${basename}..."
            go run -C website/scripts/kubespec-render ./render.go \
              -docs "$DOCS_KEY_FILE" \
              "$crd" \
              > "${TARGET_DIR}/${basename}.html"
          done

          echo "Kubespec HTMLs generated successfully:"
          ls -la "$TARGET_DIR"/*.html

      - name: Generate CEL context widget HTML
        run: |
          CEL_SCHEMA="${GITHUB_WORKSPACE}/agentgateway/schema/cel.json"
          TARGET_DIR="${GITHUB_WORKSPACE}/website/assets/agw-docs/pages/reference/cel/${{ matrix.link_version }}"
          mkdir -p "$TARGET_DIR"
  
          cd website/scripts/kubespec-render
  
          echo "Generating interactive CEL context widget HTML from schema/cel.json..."
          go run render.go -title "CEL expression context" "$CEL_SCHEMA" \
            > "${TARGET_DIR}/cel-context.html"
  
          echo "CEL widget HTML generated successfully:"
          ls -la "${TARGET_DIR}/cel-context.html"

      # Create PR: needs "Allow GitHub Actions to create and approve pull requests" (Settings → Actions)
      # or a repo secret CREATE_PR_TOKEN (PAT with pull_requests: write).
      - name: Create PR for website repo
        uses: peter-evans/create-pull-request@v7
        id: create-pr
        with:
          path: website
          base: main
          body: |
            Generate reference documentation for agentgateway (${{ matrix.link_version }}).

            Source: agentgateway/agentgateway at `${{ matrix.ref }}`.
            Updates API reference (including shared types such as CEL expression) and interactive kubespec widgets, Helm (agentgateway + agentgateway-crds), control plane metrics, and the agctl CLI reference for the ${{ matrix.link_version }} version.

            This PR was created automatically by the reference-docs workflow.

            Workflow run: https://github.com/agentgateway/website/actions/runs/${{ github.run_id }}
          branch: ref-docs-${{ matrix.link_version }}
          commit-message: |
            docs: update API (incl. shared types), kubespec widgets, Helm, metrics, and agctl CLI docs from agentgateway ${{ matrix.ref }}

            Signed-off-by: GitHub Action <action@github.com>
          committer: GitHub Action <action@github.com>
          delete-branch: true
          title: '[Automated] Update reference docs (${{ matrix.link_version }}) from agentgateway ${{ matrix.ref }}'
          token: ${{ secrets.GH_TOKEN }}

      - name: Output PR URL
        run: |
          if [ -n "${{ steps.create-pr.outputs.pull-request-url }}" ]; then
            echo "PR created: ${{ steps.create-pr.outputs.pull-request-url }}"
          else
            echo "No changes detected - PR not created"
          fi