sdk-reference-sync.yml

name: Sync SDK Reference Documentation

on:
  workflow_dispatch:
    inputs:
      sdk:
        description: "SDK to generate (see sdks.config.ts for available SDKs, or use 'all')"
        required: true
        default: "all"
        type: string
      version:
        description: "Version to generate (all, latest, or specific like v2.9.0)"
        required: true
        default: "latest"
        type: string
      limit:
        description: "Limit number of versions to generate (default: 5)"
        required: false
        default: 5
        type: number
      force:
        description: "Force regeneration of existing versions"
        required: false
        default: false
        type: boolean

  repository_dispatch:
    types: [sdk-release]
  schedule:
    - cron: "*/15 * * * *"

permissions:
  contents: write
  pull-requests: write

# prevent concurrent runs that could conflict
concurrency:
  group: sdk-reference-${{ github.ref }}
  cancel-in-progress: false

jobs:
  generate:
    runs-on: ubuntu-latest
    timeout-minutes: 30

    steps:
      - name: Generate GitHub App installation token
        id: app-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ vars.AUTOFIXER_APP_ID }}
          private-key: ${{ secrets.AUTOFIXER_APP_SECRET }}

      - name: Checkout docs repo
        uses: actions/checkout@v6
        with:
          token: ${{ steps.app-token.outputs.token }}
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

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

      - name: Cache pnpm dependencies
        uses: actions/cache@v4
        with:
          path: |
            ~/.pnpm-store
            sdk-reference-generator/node_modules
          key: ${{ runner.os }}-pnpm-${{ hashFiles('sdk-reference-generator/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
          cache: "pip"

      - name: Install generator dependencies
        working-directory: sdk-reference-generator
        run: pnpm install --frozen-lockfile

      - name: Install Python dependencies
        run: pip install -r requirements.txt

      - name: Resolve generation inputs from trigger
        id: params
        env:
          EVENT_NAME: ${{ github.event_name }}
          INPUT_SDK: ${{ github.event.inputs.sdk }}
          INPUT_VERSION: ${{ github.event.inputs.version }}
          INPUT_LIMIT: ${{ github.event.inputs.limit }}
          INPUT_FORCE: ${{ github.event.inputs.force }}
          PAYLOAD_SDK: ${{ github.event.client_payload.sdk }}
          PAYLOAD_VERSION: ${{ github.event.client_payload.version }}
          PAYLOAD_LIMIT: ${{ github.event.client_payload.limit }}
        run: bash scripts/resolve-sdk-reference-sync-params.sh

      - name: Generate SDK Reference
        working-directory: sdk-reference-generator
        env:
          SDK_NAME: ${{ steps.params.outputs.sdk }}
          SDK_VERSION: ${{ steps.params.outputs.version }}
          LIMIT: ${{ steps.params.outputs.limit }}
          FORCE: ${{ steps.params.outputs.force }}
          FORCE_COLOR: "2"
        run: |
          ARGS="--sdk $SDK_NAME --version $SDK_VERSION"

          if [[ -n "$LIMIT" && "$LIMIT" != "0" ]]; then
            ARGS="$ARGS --limit $LIMIT"
          fi

          if [[ "$FORCE" == "true" ]]; then
            ARGS="$ARGS --force"
          fi

          pnpm run generate $ARGS

      - name: Collect change details
        id: changes
        run: |
          CHANGED_FILES="$(git status --porcelain -- docs/sdk-reference docs.json | wc -l | tr -d ' ')"
          TOTAL_MDX_FILES="$(find docs/sdk-reference -type f -name '*.mdx' | wc -l | tr -d ' ')"

          if [[ "$CHANGED_FILES" == "0" ]]; then
            echo "changes=false" >> $GITHUB_OUTPUT
          else
            echo "changes=true" >> $GITHUB_OUTPUT
          fi

          echo "changed_files=$CHANGED_FILES" >> $GITHUB_OUTPUT
          echo "total_mdx_files=$TOTAL_MDX_FILES" >> $GITHUB_OUTPUT

      - name: Commit changes and manage pull request
        if: steps.changes.outputs.changes == 'true'
        id: pr
        uses: peter-evans/create-pull-request@v7
        with:
          token: ${{ steps.app-token.outputs.token }}
          branch: automation/sdk-reference-sync
          delete-branch: true
          add-paths: |
            docs/sdk-reference
            docs.json
          author: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
          committer: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
          commit-message: "docs: sync SDK reference for ${{ steps.params.outputs.sdk }} ${{ steps.params.outputs.version }}"
          title: "docs: sync SDK reference for ${{ steps.params.outputs.sdk }} ${{ steps.params.outputs.version }}"
          body: |
            ## Summary
            This automated PR syncs generated SDK reference documentation.

            ## Trigger
            - Source: `${{ steps.params.outputs.trigger }}`
            - SDK: `${{ steps.params.outputs.sdk }}`
            - Version: `${{ steps.params.outputs.version }}`
            - Limit: `${{ steps.params.outputs.limit_display }}`
            - Force: `${{ steps.params.outputs.force }}`

            ## Changes
            - Updates generated reference files under `docs/sdk-reference/**`
            - Updates `docs.json` navigation when generation changes the docs tree
            - Changed files detected in this run: `${{ steps.changes.outputs.changed_files }}`
            - Total tracked MDX reference files after generation: `${{ steps.changes.outputs.total_mdx_files }}`

            ## Run Details
            - Workflow: `${{ github.workflow }}`
            - Run: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}

      - name: Summary
        env:
          TRIGGER: ${{ steps.params.outputs.trigger }}
          SDK_NAME: ${{ steps.params.outputs.sdk }}
          SDK_VERSION: ${{ steps.params.outputs.version }}
          LIMIT: ${{ steps.params.outputs.limit_display }}
          FORCE: ${{ steps.params.outputs.force }}
          CHANGES: ${{ steps.changes.outputs.changes }}
          CHANGED_FILES: ${{ steps.changes.outputs.changed_files }}
          TOTAL_MDX_FILES: ${{ steps.changes.outputs.total_mdx_files }}
          PR_OPERATION: ${{ steps.pr.outputs.pull-request-operation }}
          PR_URL: ${{ steps.pr.outputs.pull-request-url }}
        run: |
          echo "## SDK Reference Generation Complete" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "| Parameter | Value |" >> $GITHUB_STEP_SUMMARY
          echo "|-----------|-------|" >> $GITHUB_STEP_SUMMARY
          echo "| Trigger | $TRIGGER |" >> $GITHUB_STEP_SUMMARY
          echo "| SDK | $SDK_NAME |" >> $GITHUB_STEP_SUMMARY
          echo "| Version | $SDK_VERSION |" >> $GITHUB_STEP_SUMMARY
          echo "| Limit | $LIMIT |" >> $GITHUB_STEP_SUMMARY
          echo "| Force | $FORCE |" >> $GITHUB_STEP_SUMMARY
          echo "| Changes detected | $CHANGES |" >> $GITHUB_STEP_SUMMARY
          echo "| Changed files | ${CHANGED_FILES:-0} |" >> $GITHUB_STEP_SUMMARY
          echo "| PR operation | ${PR_OPERATION:-No PR created} |" >> $GITHUB_STEP_SUMMARY
          if [[ -n "$PR_URL" ]]; then
            echo "| Pull request | $PR_URL |" >> $GITHUB_STEP_SUMMARY
          fi
          echo "" >> $GITHUB_STEP_SUMMARY

          if [[ "$CHANGES" == "true" ]]; then
            echo "### Generated Files" >> $GITHUB_STEP_SUMMARY
            echo '```' >> $GITHUB_STEP_SUMMARY
            echo "Total MDX files: $TOTAL_MDX_FILES" >> $GITHUB_STEP_SUMMARY
            echo '```' >> $GITHUB_STEP_SUMMARY
          else
            echo "No SDK reference changes were detected, so no pull request was created." >> $GITHUB_STEP_SUMMARY
          fi