sync-api-docs.yml

name: Sync Enhanced YAML Specifications from Source Repo

# This workflow runs autonomously in the destination repo - NO secrets needed in source repo!
# It enhances OpenAPI YAML files with AI-generated descriptions and syncs them to the destination.
# It can be triggered three ways:
# 1. Schedule: Runs every 6 hours, checks source repo for changes
# 2. Manual: Use workflow_dispatch to run on demand
# 3. Source notification: Optional repository_dispatch from source repo (requires source repo secrets)

on:
  # Primary trigger - runs automatically every 6 hours
  schedule:
    - cron: "0 */6 * * *" # Every 6 hours

  # Manual trigger - use this for on-demand sync
  workflow_dispatch:
    inputs:
      force_regenerate:
        description: "Force re-enhance all YAML files (ignore change detection)"
        required: false
        type: boolean
        default: false

  # Optional - only works if source repo has APP_ID and APP_PRIVATE_KEY secrets configured
  repository_dispatch:
    types: [source-yaml-updated]

jobs:
  sync_docs:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write

    steps:
      - name: Generate GitHub App Token
        uses: actions/create-github-app-token@v1
        id: app-token
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
          owner: domoinc
          repositories: internal-domo-apis

      - name: Checkout Destination Repo
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Clone Source Repo
        uses: actions/checkout@v4
        with:
          repository: domoinc/internal-domo-apis
          token: ${{ steps.app-token.outputs.token }}
          path: source-repo
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.10"

      - name: Install Dependencies
        run: |
          python -m pip install --upgrade pip
          pip install pyyaml

      # Cross-repo change detection: Compare source YAML timestamps with destination YAML
      # This is needed because we're syncing between two repos - git diff wouldn't detect these changes
      - name: Detect Changed YAML Files
        id: detect
        run: |
          python .github/scripts/detect_yaml_changes.py \
            --source source-repo/api-docs/public \
            --dest docs/API-Reference/Product-APIs \
            --force ${{ github.event.inputs.force_regenerate || 'false' }}

      - name: Check if Changes Detected
        id: check
        run: |
          if [ -f changed_files.txt ] && [ -s changed_files.txt ]; then
            echo "has_changes=true" >> $GITHUB_OUTPUT
            echo "Changed files detected:"
            cat changed_files.txt
          else
            echo "has_changes=false" >> $GITHUB_OUTPUT
            echo "No changes detected"
          fi

      # Read changed files list
      - name: Read Changed Files
        if: steps.check.outputs.has_changes == 'true'
        id: read-changes
        run: |
          {
            echo "changed_files<<EOF"
            cat changed_files.txt
            echo "EOF"
          } >> $GITHUB_OUTPUT

      # Enhance YAML files with AI-generated descriptions (action only enhances, does not create PRs)
      - name: Enhance YAML Files
        if: steps.check.outputs.has_changes == 'true'
        uses: DomoApps/documentation-generator-action@v2.0.0
        with:
          # Required
          openai_api_key: ${{ secrets.OPENAI_API_KEY }}

          # Paths
          yaml_input_path: "./source-repo/api-docs/public"
          yaml_output_path: "./temp-enhanced-yaml" # Temporary directory for enhanced YAML

          # Enhancement Configuration
          enhancement_mode: "missing_only" # Only enhance missing descriptions
          quality_threshold: "85" # Minimum quality score for AI-generated descriptions

          # AI Configuration
          openai_model: "gpt-4o" # or 'gpt-4', 'gpt-3.5-turbo'
          max_iterations: "3" # Max refinement iterations (higher = better quality, more cost)
          completeness_threshold: "90" # Overall quality threshold (0-100)
          timeout_minutes: "30" # Max processing time

          # Change Detection
          changed_files: ${{ steps.read-changes.outputs.changed_files }}
          process_changed_only: "false" # We already filtered via detect_yaml_changes.py

          # PR creation disabled - we handle it below with individual PRs
          create_pull_request: "false"

      # Create individual PRs for each enhanced YAML file
      - name: Create Individual PRs for Enhanced YAML
        if: steps.check.outputs.has_changes == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          python .github/scripts/create_individual_prs.py \
            --changed-list changed_files.txt \
            --temp-dir ./temp-enhanced-yaml \
            --dest-dir docs/API-Reference/Product-APIs \
            --base-branch master \
            --pr-branch-prefix yaml-enhance \
            --openai-model gpt-4o \
            --max-iterations 3 \
            --quality-threshold 85 \
            --repo DomoApps/domo-developer-portal

      - name: Summary
        if: always()
        run: |
          echo "## 📝 YAML Enhancement Sync Summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          if [ "${{ steps.check.outputs.has_changes }}" == "true" ]; then
            echo "✅ Changes detected and processed" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "### Changed Files:" >> $GITHUB_STEP_SUMMARY
            if [ -f changed_files.txt ]; then
              while IFS= read -r file; do
                echo "- \`$file\`" >> $GITHUB_STEP_SUMMARY
              done < changed_files.txt
            fi
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "### Actions Taken:" >> $GITHUB_STEP_SUMMARY
            echo "- Enhanced OpenAPI YAML files with AI-generated descriptions" >> $GITHUB_STEP_SUMMARY
            echo "- Synced enhanced YAML files to destination (preserving structure)" >> $GITHUB_STEP_SUMMARY
            echo "- Created individual PR per file (skipped files with existing open PRs)" >> $GITHUB_STEP_SUMMARY
            echo "- Committed enhanced YAML files to destination paths" >> $GITHUB_STEP_SUMMARY
          else
            echo "ℹ️ No changes detected - YAML files are up to date" >> $GITHUB_STEP_SUMMARY
          fi