Chore/nightly sync prs

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

@@ -1,9 +1,6 @@
 name: Sync agent-sdk OpenAPI
 
 on:
-  push:
-    branches:
-      - '**'      # run on every branch
   schedule:
     - cron: '0 2 * * *'   # nightly catch-up
   workflow_dispatch:
@@ -15,12 +12,11 @@ on:
 
 permissions:
   contents: write
+  pull-requests: write
 
 jobs:
   sync-openapi:
     runs-on: ubuntu-latest
-    # Avoid infinite loops on our own commits
-    if: github.actor != 'github-actions[bot]'
 
     env:
       # GITHUB_TOKEN is fine.
@@ -32,6 +28,7 @@ jobs:
       - name: Checkout docs repo
         uses: actions/checkout@v4
         with:
+          ref: main
           fetch-depth: 0
           persist-credentials: true
 
@@ -72,19 +69,21 @@ jobs:
             echo "changes=false" >> "$GITHUB_OUTPUT"
           fi
 
-      - name: Commit and push OpenAPI spec
+      - name: Create Pull Request with OpenAPI changes
         if: steps.detect_changes.outputs.changes == 'true'
-        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
+        uses: peter-evans/create-pull-request@v7
+        with:
+          commit-message: |
+            docs(sync-openapi): agent-sdk ${{ env.AGENT_SDK_REF }}
 
-          SHA_SHORT="$(git -C agent-sdk rev-parse --short=7 HEAD || echo manual)"
-          BRANCH="${AGENT_SDK_REF:-main}"
+            Generated from agent-sdk at `${{ env.AGENT_SDK_REF }}`.
+          title: "chore(docs): sync agent-sdk OpenAPI"
+          body: |
+            This PR was automatically created by the nightly sync workflow.
 
-          git commit -m "sync(openapi): agent-sdk/${BRANCH} ${SHA_SHORT}"
-          git push
+            It updates the OpenAPI spec to match OpenHands/agent-sdk at `${{ env.AGENT_SDK_REF }}`.
+          branch: chore/sync-openapi
+          delete-branch: true
+          signoff: false
+          add-paths: |
+            openapi/agent-sdk.json

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

@@ -1,9 +1,6 @@
 name: Sync Documentation Code Blocks
 
 on:
-  push:
-    branches:
-      - '**'   # run on every branch
   schedule:
     # Run daily at 2 AM UTC to catch any changes
     - cron: '0 2 * * *'
@@ -21,11 +18,11 @@ permissions:
 jobs:
   sync-code-blocks:
     runs-on: ubuntu-latest
-    if: github.actor != 'github-actions[bot]'
     steps:
-      - name: Checkout docs repository
+      - name: Checkout docs repository (main)
         uses: actions/checkout@v4
         with:
+          ref: main
           fetch-depth: 0
 
       - name: Checkout agent-sdk
@@ -55,15 +52,21 @@ 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 with synced changes
+        if: steps.detect_changes.outputs.changes == 'true'
+        uses: peter-evans/create-pull-request@v7
+        with:
+          commit-message: |
+            docs(sync): code blocks from agent-sdk
+
+            Synced from agent-sdk ref: ${{ github.event.inputs.agent_sdk_ref || 'main' }}
+          title: "chore(docs): sync code blocks from agent-sdk"
+          body: |
+            This PR was automatically created by the nightly sync workflow.
+
+            It updates SDK guide code blocks to match the source examples in OpenHands/agent-sdk at `${{ github.event.inputs.agent_sdk_ref || 'main' }}`.
 
-          Synced from agent-sdk ref: ${{ github.event.inputs.agent_sdk_ref || 'main' }}"
-          git push
+            If additional changes are included, please review them carefully.
+          branch: chore/sync-docs-code-blocks
+          delete-branch: true
+          signoff: false

.openhands/microagents/sdk-guidelines.md

@@ -243,9 +243,9 @@ You can check https://www.mintlify.com/docs for documentation on what our doc si
 
 ### Code Synchronization Workflow
 - **File**: `.github/workflows/sync-docs-code-blocks.yml`
-- **Triggers**: Push to any branch, daily at 2 AM UTC, manual dispatch
+- **Triggers**: Nightly at 2 AM UTC and manual dispatch
 - **Purpose**: Keeps code blocks in sync with agent-sdk examples
-- **Actions**: Checks out both repositories, runs sync script, commits changes if needed
+- **Actions**: Checks out both repositories, runs sync script, and opens a dedicated PR if changes are found (does not modify unrelated PR branches)
 
 ### OpenAPI Sync Workflow
 - **File**: `.github/workflows/sync-agent-sdk-openapi.yml`