Generate API reference docs for agentgateway #10
Workflow file for this run
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # 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. | |
| name: Generate API reference docs for agentgateway | |
| on: | |
| release: | |
| types: [created] | |
| workflow_dispatch: | |
| inputs: | |
| doc_version: | |
| description: 'Doc version to generate (must match a version in hugo.yaml), e.g. 1.0.x' | |
| required: true | |
| default: '1.0.x' | |
| jobs: | |
| setup: | |
| name: Setup and validate | |
| runs-on: ubuntu-22.04 | |
| outputs: | |
| ref: ${{ steps.resolve_ref.outputs.ref }} | |
| link_version: ${{ steps.version_variables.outputs.link_version }} | |
| doc_version: ${{ steps.version_variables.outputs.doc_version }} | |
| steps: | |
| - name: Checkout website repo | |
| uses: actions/checkout@v4 | |
| with: | |
| path: website | |
| fetch-depth: 1 | |
| - name: Resolve version from hugo.yaml | |
| id: version_variables | |
| run: | | |
| if [[ "${{ github.event_name }}" == "release" ]]; then | |
| doc_version="1.0.x" | |
| else | |
| doc_version="${{ inputs.doc_version }}" | |
| fi | |
| echo "doc_version=${doc_version}" >> $GITHUB_OUTPUT | |
| link_version=$(python3 -c " | |
| import yaml, sys | |
| with open('website/hugo.yaml') as f: | |
| cfg = yaml.safe_load(f) | |
| versions = cfg['params']['sections']['standalone']['versions'] | |
| entry = next((v for v in versions if v['version'] == sys.argv[1]), None) | |
| if not entry: | |
| valid = [v['version'] for v in versions] | |
| print(f'Error: version {sys.argv[1]} not found in hugo.yaml. Valid versions: {valid}', file=sys.stderr) | |
| sys.exit(1) | |
| print(entry['linkVersion']) | |
| " "$doc_version") | |
| if [[ -z "$link_version" ]]; then | |
| echo "Error: failed to resolve linkVersion from hugo.yaml" | |
| exit 1 | |
| fi | |
| echo "link_version=${link_version}" >> $GITHUB_OUTPUT | |
| echo "Using ${doc_version}: linkVersion=${link_version}, apiFile=api-${link_version}.md" | |
| - name: Resolve and verify agentgateway ref | |
| id: resolve_ref | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| run: | | |
| LINK_VERSION="${{ steps.version_variables.outputs.link_version }}" | |
| DOC_VERSION="${{ steps.version_variables.outputs.doc_version }}" | |
| if [[ "$LINK_VERSION" == "main" ]]; then | |
| echo "Using 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 | |
| echo "ref=main" >> $GITHUB_OUTPUT | |
| else | |
| # Derive tag prefix from version string: "1.0.x" -> "v1.0." | |
| TAG_PREFIX=$(echo "$DOC_VERSION" | sed 's/\.[^.]*$/\./' | sed 's/^/v/') | |
| echo "Resolving latest tag with prefix ${TAG_PREFIX}..." | |
| LATEST=$(gh api repos/agentgateway/agentgateway/tags --paginate \ | |
| --jq '.[].name' | grep "^${TAG_PREFIX}" | sort -V | tail -1) | |
| if [[ -z "$LATEST" ]]; then | |
| echo "Error: no tags found matching prefix ${TAG_PREFIX} in agentgateway/agentgateway" | |
| exit 1 | |
| fi | |
| echo "Resolved to tag: ${LATEST}" | |
| echo "ref=${LATEST}" >> $GITHUB_OUTPUT | |
| fi | |
| api-docs: | |
| name: Generate API docs | |
| runs-on: ubuntu-22.04 | |
| needs: setup | |
| env: | |
| GOTOOLCHAIN: auto | |
| steps: | |
| - name: Checkout website repo | |
| uses: actions/checkout@v4 | |
| with: | |
| token: ${{ secrets.GITHUB_TOKEN }} | |
| path: website | |
| fetch-depth: 0 | |
| - name: Setup Go for docs generation | |
| uses: actions/setup-go@v6 | |
| with: | |
| go-version: 1.25.7 | |
| cache: false | |
| - name: Checkout agentgateway source repository | |
| uses: actions/checkout@v4 | |
| with: | |
| repository: agentgateway/agentgateway | |
| token: ${{ secrets.GITHUB_TOKEN }} | |
| path: agentgateway | |
| ref: ${{ needs.setup.outputs.ref }} | |
| - name: Generate agentgateway API docs | |
| run: | | |
| pushd website || exit 1 | |
| LINK_VERSION="${{ needs.setup.outputs.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" | |
| 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="${{ needs.setup.outputs.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="${{ needs.setup.outputs.link_version }}" \ | |
| WEBSITE_DIR="website" \ | |
| KGATEWAY_DIR="agentgateway/controller" \ | |
| python3 website/scripts/generate-ref-docs.py | |
| # 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 (${{ needs.setup.outputs.link_version }}). | |
| Source: agentgateway/agentgateway at `${{ needs.setup.outputs.ref }}`. | |
| Updates API reference (including shared types such as CEL expression), Helm (agentgateway + agentgateway-crds), and control plane metrics for the ${{ needs.setup.outputs.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-${{ needs.setup.outputs.link_version }} | |
| commit-message: 'docs: update API (incl. shared types), Helm, and metrics docs from agentgateway ${{ needs.setup.outputs.ref }}' | |
| committer: GitHub Action <action@github.com> | |
| delete-branch: true | |
| title: '[Automated] Update reference docs (${{ needs.setup.outputs.link_version }}) from agentgateway ${{ needs.setup.outputs.ref }}' | |
| token: ${{ secrets.CREATE_PR_TOKEN || secrets.GITHUB_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 |