docs: handle PR permission restrictions in sync workflow (#161)

* docs: handle PR permission restrictions in sync workflow

* docs: use GitHub App token for sdk sync PRs

Author: ben-fornefeld

.github/workflows/sdk-reference-sync.yml

@@ -29,6 +29,10 @@ on:
   schedule:
     - cron: "*/15 * * * *"
 
+permissions:
+  contents: write
+  pull-requests: write
+
 # prevent concurrent runs that could conflict
 concurrency:
   group: sdk-reference-${{ github.ref }}
@@ -38,14 +42,19 @@ jobs:
   generate:
     runs-on: ubuntu-latest
     timeout-minutes: 30
-    permissions:
-      contents: write
-      pull-requests: write
 
     steps:
+      - name: Generate GitHub App installation token
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ vars.AUTOFIXER_APP_ID }}
+          private-key: ${{ secrets.AUTOFIXER_APP_SECRET }}
+
       - name: Checkout docs repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
+          token: ${{ steps.app-token.outputs.token }}
           fetch-depth: 0
 
       - name: Setup Node.js
@@ -133,21 +142,38 @@ jobs:
       - name: Commit changes and manage pull request
         if: steps.changes.outputs.changes == 'true'
         id: pr
-        env:
-          GH_TOKEN: ${{ github.token }}
-          BASE_BRANCH: ${{ github.ref_name }}
-          BRANCH_NAME: automation/sdk-reference-sync
-          TRIGGER: ${{ steps.params.outputs.trigger }}
-          SDK_NAME: ${{ steps.params.outputs.sdk }}
-          SDK_VERSION: ${{ steps.params.outputs.version }}
-          LIMIT_DISPLAY: ${{ steps.params.outputs.limit_display }}
-          FORCE: ${{ steps.params.outputs.force }}
-          CHANGED_FILES: ${{ steps.changes.outputs.changed_files }}
-          TOTAL_MDX_FILES: ${{ steps.changes.outputs.total_mdx_files }}
-          WORKFLOW_NAME: ${{ github.workflow }}
-          REPOSITORY: ${{ github.repository }}
-          RUN_ID: ${{ github.run_id }}
-        run: bash scripts/create-sdk-reference-sync-pr.sh
+        uses: peter-evans/create-pull-request@v7
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          branch: automation/sdk-reference-sync
+          delete-branch: true
+          add-paths: |
+            docs/sdk-reference
+            docs.json
+          author: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
+          committer: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
+          commit-message: docs: sync SDK reference for ${{ steps.params.outputs.sdk }} ${{ steps.params.outputs.version }}
+          title: docs: sync SDK reference for ${{ steps.params.outputs.sdk }} ${{ steps.params.outputs.version }}
+          body: |
+            ## Summary
+            This automated PR syncs generated SDK reference documentation.
+
+            ## Trigger
+            - Source: `${{ steps.params.outputs.trigger }}`
+            - SDK: `${{ steps.params.outputs.sdk }}`
+            - Version: `${{ steps.params.outputs.version }}`
+            - Limit: `${{ steps.params.outputs.limit_display }}`
+            - Force: `${{ steps.params.outputs.force }}`
+
+            ## Changes
+            - Updates generated reference files under `docs/sdk-reference/**`
+            - Updates `docs.json` navigation when generation changes the docs tree
+            - Changed files detected in this run: `${{ steps.changes.outputs.changed_files }}`
+            - Total tracked MDX reference files after generation: `${{ steps.changes.outputs.total_mdx_files }}`
+
+            ## Run Details
+            - Workflow: `${{ github.workflow }}`
+            - Run: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}
 
       - name: Summary
         env:
@@ -159,8 +185,8 @@ jobs:
           CHANGES: ${{ steps.changes.outputs.changes }}
           CHANGED_FILES: ${{ steps.changes.outputs.changed_files }}
           TOTAL_MDX_FILES: ${{ steps.changes.outputs.total_mdx_files }}
-          PR_OPERATION: ${{ steps.pr.outputs.operation }}
-          PR_URL: ${{ steps.pr.outputs.url }}
+          PR_OPERATION: ${{ steps.pr.outputs.pull-request-operation }}
+          PR_URL: ${{ steps.pr.outputs.pull-request-url }}
         run: |
           echo "## SDK Reference Generation Complete" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY