update-docs.yml

name: Update Documentation

on:
  push:
    branches: ["main"]
    paths:
      - 'helm_sdkpy/**'
      - 'scripts/update_docs_version.py'
      - 'pyproject.toml'
      - 'docusaurus/**'
  workflow_dispatch:

concurrency:
  group: "update-docs"
  cancel-in-progress: true

permissions:
  contents: write
  pull-requests: write
  id-token: write
  pages: write

env:
  BASE_BRANCH: main

jobs:
  update-docs:
    name: Update Documentation
    runs-on: ubuntu-24.04
    environment: github-pages

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          # GITHUB_TOKEN is provided automatically; no need to pass from secrets
          token: ${{ github.token }}

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: yarn
          cache-dependency-path: docusaurus/yarn.lock

      - name: Install just
        run: sudo snap install just --classic

      - name: Install UV
        run: sudo snap install astral-uv --classic

      - name: Ensure GitHub CLI auth
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh --version
          gh auth status -h github.com

      - name: Create docs update branch & commit
        id: commit_changes
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          set -euo pipefail

          BRANCH_NAME="docs/auto-update-$(date +%Y%m%d-%H%M%S)"

          # Make sure base exists locally and is up to date
          git fetch origin --prune
          if ! git ls-remote --exit-code --heads origin "${BASE_BRANCH}" >/dev/null 2>&1; then
            echo "Base branch '${BASE_BRANCH}' not found on origin." >&2
            exit 1
          fi
          git checkout -B "${BASE_BRANCH}" "origin/${BASE_BRANCH}"

          # Create/update working branch from base
          git switch -C "${BRANCH_NAME}"

          just docs-build

          # Stage only intended paths
          git add docusaurus/ || true

          # Check if anything changed
          if git diff --cached --quiet; then
            echo "changes=false" >> "$GITHUB_OUTPUT"
            echo "No changes detected; skipping PR."
           exit 0
          fi

          git config user.name  "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"

          git commit -m "docs: auto-update generated documentation

          - Updated CLI command documentation
          - Regenerated Docusaurus build files
          - Updated version information

          Auto-generated by GitHub Actions"

          git push -u origin "${BRANCH_NAME}"

          echo "branch=${BRANCH_NAME}" >> "$GITHUB_OUTPUT"
          echo "changes=true" >> "$GITHUB_OUTPUT"

      - name: Open PR
        if: steps.commit_changes.outputs.changes == 'true'
        id: open_pr
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          set -euo pipefail
          BRANCH_NAME="${{ steps.commit_changes.outputs.branch }}"

          # Create PR targeting main (change if you use a different base)
          if ! PR_URL=$(
            gh pr create \
              --base "${BASE_BRANCH}" \
              --label "deploy-docs" \
              --label "auto-merge" \
              --title "docs: auto-update generated documentation" \
              --body $'🤖 **Automated Documentation Update**\n\n- ✅ Updated CLI command documentation\n- ✅ Regenerated Docusaurus build files\n- ✅ Updated version information\n\n> Created by GitHub Actions.'
          ); then
            echo "PR create failed—attempting to fetch existing PR…"
            PR_URL="$(gh pr view "${BRANCH_NAME}" --json url -q .url || true)"
          fi

          if [ -z "${PR_URL}" ]; then
            echo "Could not create or find the PR." >&2
            exit 1
          fi

          echo "url=${PR_URL}" >> "$GITHUB_OUTPUT"
          echo "PR_URL=${PR_URL}" >> "$GITHUB_ENV"
          echo "Opened PR: ${PR_URL}"

      - name: Merge or enable auto-merge
        if: steps.commit_changes.outputs.changes == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
          PR_URL: ${{ steps.open_pr.outputs.url }}
        run: |
          set -euo pipefail
      
          # Fetch PR status
          ms=$(gh pr view "$PR_URL" --json mergeStateStatus -q .mergeStateStatus)
          rd=$(gh pr view "$PR_URL" --json reviewDecision -q .reviewDecision)
          draft=$(gh pr view "$PR_URL" --json isDraft -q .isDraft)
      
          echo "mergeStateStatus=${ms}"
          echo "reviewDecision=${rd}"
          echo "isDraft=${draft}"
      
          case "$ms" in
            CLEAN)
              echo "PR is clean/mergeable now. Merging immediately…"
              gh pr merge "$PR_URL" --squash --delete-branch
              ;;
      
            BLOCKED|BEHIND|UNSTABLE|DIRTY)
              echo "PR is not immediately mergeable (status: $ms). Attempting to enable auto-merge…"
              # Will succeed only if repo has Auto-merge enabled and required conditions will pass later.
              if gh pr merge "$PR_URL" --squash --auto; then
                echo "Auto-merge enabled."
              else
                echo "Could not enable auto-merge. Likely reasons:"
                echo " - Repo hasn’t enabled Auto-merge (Settings → Pull requests → Enable auto-merge)"
                echo " - Required reviews/checks not satisfied (reviewDecision=$rd, draft=$draft)"
                echo " - Branch is behind or needs an update (status=$ms)"
                exit 1
              fi
              ;;
      
            *)
              echo "Unexpected mergeStateStatus: $ms"
              gh pr view "$PR_URL" --json url,mergeable,mergeStateStatus,reviewDecision,isDraft,requiredStatusCheckContexts
              exit 1
              ;;
          esac

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Upload build directory
          path: './docusaurus/build'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

      - name: Gather context
        id: ctx
        run: |
          echo "sha=$(git rev-parse --short HEAD || echo $GITHUB_SHA)" >> $GITHUB_OUTPUT
          echo "ref=$GITHUB_REF" >> $GITHUB_OUTPUT
          echo "repo=${GITHUB_REPOSITORY}" >> $GITHUB_OUTPUT
          echo "actor=${GITHUB_ACTOR}" >> $GITHUB_OUTPUT

    # Optional: prevent overlapping dispatches
    concurrency:
      group: notify-platform-${{ github.ref }}
      cancel-in-progress: false