Create generated docs sync PRs

Author: koxudaxi

.github/workflows/generated-docs-sync.yaml

@@ -86,13 +86,12 @@ jobs:
           path: ${{ runner.temp }}/generated-docs.patch
           if-no-files-found: error
 
-  push:
+  create-sync-pr:
     needs: generate
+    if: needs.generate.outputs.has_changes == 'true'
     runs-on: ubuntu-latest
     permissions:
-      contents: write
-    outputs:
-      final_sha: ${{ steps.record_sha.outputs.final_sha }}
+      contents: read
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
@@ -105,15 +104,21 @@ jobs:
         with:
           name: generated-docs-patch
           path: ${{ runner.temp }}
-      # Use GITHUB_TOKEN intentionally so this sync commit does not fan out into
-      # another push-triggered workflow run. Docs deployment is chained below.
-      - name: Commit generated docs
-        if: needs.generate.outputs.has_changes == 'true'
+      # Use a narrowly-scoped GitHub App token so branch/PR events run normal
+      # checks without granting the workflow permission to bypass main rules.
+      - name: Create GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@67018539274d69449ef7c02e8e71183d1719ab42 # v2.1.4
+        with:
+          app-id: ${{ secrets.GENERATED_DOCS_APP_ID }}
+          private-key: ${{ secrets.GENERATED_DOCS_APP_PRIVATE_KEY }}
+      - name: Create or update generated docs PR
         env:
-          GH_TOKEN: ${{ github.token }}
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
           TARGET_REPO: ${{ github.repository }}
           TARGET_REF: ${{ github.ref_name }}
           PATCH_PATH: ${{ runner.temp }}/generated-docs.patch
+          SYNC_BRANCH: docs/generated-docs-sync
         run: |
           set -euo pipefail
           git apply --index --whitespace=nowarn "$PATCH_PATH"
@@ -123,25 +128,55 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git commit -m "docs: sync generated docs"
-          git fetch origin "${TARGET_REF}"
-          git rebase "origin/${TARGET_REF}"
-          git push "https://x-access-token:${GH_TOKEN}@github.com/${TARGET_REPO}.git" "HEAD:${TARGET_REF}"
-      - name: Record final revision
-        id: record_sha
-        env:
-          DEFAULT_SHA: ${{ github.sha }}
-        run: |
-          if [ "${{ needs.generate.outputs.has_changes }}" = "true" ]; then
-            echo "final_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
+          remote_url="https://x-access-token:${GH_TOKEN}@github.com/${TARGET_REPO}.git"
+          remote_sha="$(git ls-remote --heads "$remote_url" "$SYNC_BRANCH" | awk '{print $1}')"
+          if [ -n "$remote_sha" ]; then
+            git push --force-with-lease="refs/heads/${SYNC_BRANCH}:${remote_sha}" \
+              "$remote_url" \
+              "HEAD:refs/heads/${SYNC_BRANCH}"
+          else
+            git push "$remote_url" "HEAD:refs/heads/${SYNC_BRANCH}"
+          fi
+
+          pr_body="$(mktemp)"
+          cat > "$pr_body" <<EOF
+          Generated docs are out of sync with main.
+
+          This PR was created automatically after a push to ${TARGET_REF} at ${GITHUB_SHA}.
+          EOF
+
+          target_owner="${TARGET_REPO%%/*}"
+          existing_pr="$(
+            gh pr list \
+              --repo "$TARGET_REPO" \
+              --base "$TARGET_REF" \
+              --head "${target_owner}:${SYNC_BRANCH}" \
+              --state open \
+              --json number \
+              --jq '.[0].number // empty'
+          )"
+
+          if [ -n "$existing_pr" ]; then
+            gh pr edit "$existing_pr" \
+              --repo "$TARGET_REPO" \
+              --title "Sync generated docs" \
+              --body-file "$pr_body"
           else
-            echo "final_sha=${DEFAULT_SHA}" >> "$GITHUB_OUTPUT"
+            gh pr create \
+              --repo "$TARGET_REPO" \
+              --base "$TARGET_REF" \
+              --head "${target_owner}:${SYNC_BRANCH}" \
+              --title "Sync generated docs" \
+              --body-file "$pr_body"
           fi
 
   deploy-docs:
-    needs: push
+    needs: [generate, create-sync-pr]
+    if: always() && needs.generate.result == 'success' && needs.generate.outputs.has_changes == 'false'
     uses: ./.github/workflows/docs-deploy.yaml
     with:
-      checkout_ref: ${{ needs.push.outputs.final_sha }}
+      checkout_ref: ${{ github.sha }}
       deploy_branch: dev
     secrets:
       CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}