fix(ci): reuse existing open docs PR instead of creating duplicates (#1461)

* fix(ci): reuse existing open docs PR instead of creating duplicates

The release workflow now checks for an existing open "regenerate API
documentation" PR before creating a new one. If found, it pushes new
docs changes to that PR's branch instead of spawning a duplicate.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(ci): address review findings in docs PR reuse logic

- Use git checkout -B to reset branch to current HEAD (avoids dirty
  working tree conflict and keeps freshly generated docs)
- Use --force-with-lease for push since branch history is rewritten
- Guard git commit with diff --cached --quiet for no-change case
- Handle gh pr list failure gracefully with fallback to new PR
- Narrow PR search with --author and in:title filters
- Use separate CREATE_PR variable instead of dual-purpose state

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: KyleAMathews

.github/workflows/release.yml

@@ -50,17 +50,34 @@ jobs:
             git config user.name "github-actions[bot]"
             git config user.email "github-actions[bot]@users.noreply.github.com"
 
-            BRANCH="docs/auto-update-$(date +%s)"
-            git checkout -b "$BRANCH"
+            EXISTING_BRANCH=$(gh pr list --author "app/github-actions" --search "docs: regenerate API documentation in:title" --state open --json headRefName --jq '.[0].headRefName' 2>/dev/null || echo "")
+            CREATE_PR=true
+
+            if [ -n "$EXISTING_BRANCH" ] && [ "$EXISTING_BRANCH" != "null" ]; then
+              BRANCH="$EXISTING_BRANCH"
+              echo "Found existing docs PR on branch $BRANCH, updating it"
+              git checkout -B "$BRANCH"
+              CREATE_PR=false
+            else
+              BRANCH="docs/auto-update-$(date +%s)"
+              git checkout -b "$BRANCH"
+            fi
+
             git add docs/
+            if git diff --cached --quiet; then
+              echo "No new docs changes to commit"
+              exit 0
+            fi
             git commit -m "docs: regenerate API documentation"
-            git push origin "$BRANCH"
+            git push --force-with-lease origin "$BRANCH"
 
-            gh pr create \
-              --title "docs: regenerate API documentation" \
-              --body "Automated documentation update from release" \
-              --base main \
-              --head "$BRANCH"
+            if [ "$CREATE_PR" = true ]; then
+              gh pr create \
+                --title "docs: regenerate API documentation" \
+                --body "Automated documentation update from release" \
+                --base main \
+                --head "$BRANCH"
+            fi
           else
             echo "No changes in generated docs"
           fi