From e6b0b061dd99523d96c7b32efe287926538fd952 Mon Sep 17 00:00:00 2001
From: Kyle Mathews <mathews.kyle@gmail.com>
Date: Tue, 7 Apr 2026 09:03:48 -0600
Subject: [PATCH 1/2] 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>
---
 .github/workflows/release.yml | 32 ++++++++++++++++++++++----------
 1 file changed, 22 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 2e49cf139..fc70bb6a5 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -50,17 +50,29 @@ 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"
-            git add docs/
-            git commit -m "docs: regenerate API documentation"
-            git push origin "$BRANCH"
+            EXISTING_PR=$(gh pr list --search "docs: regenerate API documentation" --state open --json number,headRefName --jq '.[0]')
 
-            gh pr create \
-              --title "docs: regenerate API documentation" \
-              --body "Automated documentation update from release" \
-              --base main \
-              --head "$BRANCH"
+            if [ -n "$EXISTING_PR" ] && [ "$EXISTING_PR" != "null" ]; then
+              BRANCH=$(echo "$EXISTING_PR" | jq -r '.headRefName')
+              echo "Found existing docs PR on branch $BRANCH, updating it"
+              git checkout "$BRANCH"
+              git pull origin "$BRANCH"
+              git add docs/
+              git commit -m "docs: regenerate API documentation"
+              git push origin "$BRANCH"
+            else
+              BRANCH="docs/auto-update-$(date +%s)"
+              git checkout -b "$BRANCH"
+              git add docs/
+              git commit -m "docs: regenerate API documentation"
+              git push origin "$BRANCH"
+
+              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

From a001da62fa0fe4dc2d07caa8b3c9b1e4defdb450 Mon Sep 17 00:00:00 2001
From: Kyle Mathews <mathews.kyle@gmail.com>
Date: Tue, 7 Apr 2026 11:30:33 -0600
Subject: [PATCH 2/2] 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>
---
 .github/workflows/release.yml | 27 ++++++++++++++++-----------
 1 file changed, 16 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index fc70bb6a5..6c5d363b9 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -50,23 +50,28 @@ jobs:
             git config user.name "github-actions[bot]"
             git config user.email "github-actions[bot]@users.noreply.github.com"
 
-            EXISTING_PR=$(gh pr list --search "docs: regenerate API documentation" --state open --json number,headRefName --jq '.[0]')
+            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_PR" ] && [ "$EXISTING_PR" != "null" ]; then
-              BRANCH=$(echo "$EXISTING_PR" | jq -r '.headRefName')
+            if [ -n "$EXISTING_BRANCH" ] && [ "$EXISTING_BRANCH" != "null" ]; then
+              BRANCH="$EXISTING_BRANCH"
               echo "Found existing docs PR on branch $BRANCH, updating it"
-              git checkout "$BRANCH"
-              git pull origin "$BRANCH"
-              git add docs/
-              git commit -m "docs: regenerate API documentation"
-              git push origin "$BRANCH"
+              git checkout -B "$BRANCH"
+              CREATE_PR=false
             else
               BRANCH="docs/auto-update-$(date +%s)"
               git checkout -b "$BRANCH"
-              git add docs/
-              git commit -m "docs: regenerate API documentation"
-              git push origin "$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 --force-with-lease origin "$BRANCH"
 
+            if [ "$CREATE_PR" = true ]; then
               gh pr create \
                 --title "docs: regenerate API documentation" \
                 --body "Automated documentation update from release" \