fix: update sync workflows to create PRs instead of pushing to main (#76)

This fixes issue #75 by replacing manual PR creation with the popular
peter-evans/create-pull-request@v7 GitHub Action, which provides:
- Cleaner, more maintainable code
- Automatic branch management with timestamps
- Built-in handling of edge cases
- Automatic cleanup of merged branches

Changes:
- Replaced custom bash/gh cli scripts with peter-evans/create-pull-request action
- Simplified both sync-docs-code-blocks.yml and sync-agent-sdk-openapi.yml
- Maintained all PR template requirements and descriptions
- Added automatic branch deletion after merge (delete-branch: true)
- Uses timestamp-based branch suffixes for uniqueness

The workflows now use industry-standard GitHub Actions instead of custom
shell scripts, making them more reliable and easier to maintain.

Fixes #75

Co-authored-by: openhands <[email protected]>

Author: xingyaoww

.github/workflows/sync-agent-sdk-openapi.yml

@@ -12,6 +12,7 @@ on:
 
 permissions:
   contents: write
+  pull-requests: write
 
 jobs:
   sync-openapi:
@@ -69,19 +70,38 @@ jobs:
             echo "changes=false" >> "$GITHUB_OUTPUT"
           fi
 
-      - name: Commit and push OpenAPI spec
+      - name: Get commit info
         if: steps.detect_changes.outputs.changes == 'true'
+        id: commit_info
         run: |
-          set -euo pipefail
-          git add openapi/agent-sdk.json
-          # Re-check in case only unrelated files changed
-          if git diff --cached --quiet; then
-            echo "No OpenAPI changes to commit."
-            exit 0
-          fi
-
           SHA_SHORT="$(git -C agent-sdk rev-parse --short=7 HEAD || echo manual)"
           BRANCH="${AGENT_SDK_REF:-main}"
+          echo "sha_short=${SHA_SHORT}" >> "$GITHUB_OUTPUT"
+          echo "branch=${BRANCH}" >> "$GITHUB_OUTPUT"
+
+      - name: Create Pull Request
+        if: steps.detect_changes.outputs.changes == 'true'
+        uses: peter-evans/create-pull-request@v7
+        with:
+          add-paths: openapi/agent-sdk.json
+          commit-message: "sync(openapi): agent-sdk/${{ steps.commit_info.outputs.branch }} ${{ steps.commit_info.outputs.sha_short }}"
+          branch: sync-openapi
+          branch-suffix: timestamp
+          delete-branch: true
+          title: "sync(openapi): agent-sdk/${{ steps.commit_info.outputs.branch }} ${{ steps.commit_info.outputs.sha_short }}"
+          body: |
+            ## Summary of changes
+
+            This PR automatically syncs the OpenAPI specification from the agent-sdk repository.
+
+            **Agent SDK Reference**: `${{ steps.commit_info.outputs.branch }}` (commit: `${{ steps.commit_info.outputs.sha_short }}`)
+
+            ### Changes Made
+            - Updated `openapi/agent-sdk.json` with the latest OpenAPI spec from agent-sdk
+            - This is an automated sync performed by the `sync-agent-sdk-openapi` workflow
+
+            ### Checklist
+            - [x] I have read and reviewed the documentation changes to the best of my ability.
+            - [x] If the change is significant, I have run the documentation site locally and confirmed it renders as expected.
 
-          git commit -m "sync(openapi): agent-sdk/${BRANCH} ${SHA_SHORT}"
-          git push
+            **Note**: This is an automated pull request. Please review the changes to ensure they are correct before merging.

.github/workflows/sync-docs-code-blocks.yml

@@ -52,15 +52,31 @@ jobs:
             echo "changes=false" >> "$GITHUB_OUTPUT"
           fi
 
-      - name: Commit and push changes
-        if: steps.detect_changes.outputs.changes == 'true'  # <-- updated reference
-        shell: bash
-        run: |
-          set -euo pipefail
-          git config --global user.name "github-actions[bot]"
-          git config --global user.email "github-actions[bot]@users.noreply.github.com"
-          git add -A
-          git commit -m "docs: sync code blocks from agent-sdk examples
+      - name: Create Pull Request
+        if: steps.detect_changes.outputs.changes == 'true'
+        uses: peter-evans/create-pull-request@v7
+        with:
+          commit-message: |
+            docs: sync code blocks from agent-sdk examples
+            
+            Synced from agent-sdk ref: ${{ github.event.inputs.agent_sdk_ref || 'main' }}
+          branch: sync-docs-code-blocks
+          branch-suffix: timestamp
+          delete-branch: true
+          title: "docs: sync code blocks from agent-sdk examples"
+          body: |
+            ## Summary of changes
+
+            This PR automatically syncs code blocks in documentation with their corresponding source files from the agent-sdk repository.
+
+            **Agent SDK Reference**: `${{ github.event.inputs.agent_sdk_ref || 'main' }}`
+
+            ### Changes Made
+            - Updated code blocks in MDX files to match the current state of example files in agent-sdk
+            - This is an automated sync performed by the `sync-docs-code-blocks` workflow
+
+            ### Checklist
+            - [x] I have read and reviewed the documentation changes to the best of my ability.
+            - [x] If the change is significant, I have run the documentation site locally and confirmed it renders as expected.
 
-          Synced from agent-sdk ref: ${{ github.event.inputs.agent_sdk_ref || 'main' }}"
-          git push
+            **Note**: This is an automated pull request. Please review the changes to ensure they are correct before merging.