From aea84ed7aa224f5c1b4d8356dc9cb0693101da3d Mon Sep 17 00:00:00 2001 From: enyst Date: Thu, 23 Oct 2025 22:52:01 +0000 Subject: [PATCH 1/4] ci(docs): run sync workflows nightly only and open dedicated PRs - Remove push triggers to avoid running on unrelated PRs - Code blocks sync: use peter-evans/create-pull-request to open chore/sync-docs-code-blocks - OpenAPI sync: use PR flow on chore/sync-openapi and restrict paths Co-authored-by: openhands --- .github/workflows/sync-agent-sdk-openapi.yml | 34 +++++++++----------- .github/workflows/sync-docs-code-blocks.yml | 32 +++++++++--------- 2 files changed, 33 insertions(+), 33 deletions(-) diff --git a/.github/workflows/sync-agent-sdk-openapi.yml b/.github/workflows/sync-agent-sdk-openapi.yml index cb610367..6177eba5 100644 --- a/.github/workflows/sync-agent-sdk-openapi.yml +++ b/.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. @@ -72,19 +68,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 diff --git a/.github/workflows/sync-docs-code-blocks.yml b/.github/workflows/sync-docs-code-blocks.yml index 72dfeb50..f6e35bcd 100644 --- a/.github/workflows/sync-docs-code-blocks.yml +++ b/.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,7 +18,6 @@ permissions: jobs: sync-code-blocks: runs-on: ubuntu-latest - if: github.actor != 'github-actions[bot]' steps: - name: Checkout docs repository uses: actions/checkout@v4 @@ -55,15 +51,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 From e179838c216348b1be646f2dbe2ed10878a94778 Mon Sep 17 00:00:00 2001 From: enyst Date: Thu, 23 Oct 2025 22:53:41 +0000 Subject: [PATCH 2/4] docs: update SDK CI guidelines to reflect nightly PR-based sync workflows Co-authored-by: openhands --- .openhands/microagents/sdk-guidelines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.openhands/microagents/sdk-guidelines.md b/.openhands/microagents/sdk-guidelines.md index 49bacf65..4535c94f 100644 --- a/.openhands/microagents/sdk-guidelines.md +++ b/.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` From 360d7c04925bc30ef5e8fa36d825427158d51d41 Mon Sep 17 00:00:00 2001 From: enyst Date: Sat, 25 Oct 2025 15:36:10 +0000 Subject: [PATCH 3/4] ci: allow sync workflows to create PRs via PAT; base runs on main\n\n- Checkout main before syncing to avoid PR-context restrictions\n- Use CREATE_PR_TOKEN input for create-pull-request with PAT fallback\n- Keep GITHUB_TOKEN as fallback when PAT not set\n\nCo-authored-by: openhands --- .github/workflows/sync-agent-sdk-openapi.yml | 4 ++++ .github/workflows/sync-docs-code-blocks.yml | 7 ++++++- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/.github/workflows/sync-agent-sdk-openapi.yml b/.github/workflows/sync-agent-sdk-openapi.yml index 6177eba5..91e6d1a8 100644 --- a/.github/workflows/sync-agent-sdk-openapi.yml +++ b/.github/workflows/sync-agent-sdk-openapi.yml @@ -21,6 +21,8 @@ jobs: env: # GITHUB_TOKEN is fine. GH_CLONE_TOKEN: ${{ secrets.GITHUB_TOKEN }} + # Token used for creating PRs. Prefer a PAT secret if available. + CREATE_PR_TOKEN: ${{ secrets.DOCS_SYNC_PR_TOKEN || secrets.OPENHANDS_BOT_PAT || secrets.GH_TOKEN || github.token }} # For workflow_dispatch this will be set; for push/schedule it will fall back to main. AGENT_SDK_REF: ${{ github.event.inputs.agent_sdk_ref || 'main' }} @@ -28,6 +30,7 @@ jobs: - name: Checkout docs repo uses: actions/checkout@v4 with: + ref: main fetch-depth: 0 persist-credentials: true @@ -72,6 +75,7 @@ jobs: if: steps.detect_changes.outputs.changes == 'true' uses: peter-evans/create-pull-request@v7 with: + token: ${{ env.CREATE_PR_TOKEN }} commit-message: | docs(sync-openapi): agent-sdk ${{ env.AGENT_SDK_REF }} diff --git a/.github/workflows/sync-docs-code-blocks.yml b/.github/workflows/sync-docs-code-blocks.yml index f6e35bcd..c9926166 100644 --- a/.github/workflows/sync-docs-code-blocks.yml +++ b/.github/workflows/sync-docs-code-blocks.yml @@ -18,10 +18,14 @@ permissions: jobs: sync-code-blocks: runs-on: ubuntu-latest + env: + # Prefer a PAT if available to create PRs, then fall back to GITHUB_TOKEN + CREATE_PR_TOKEN: ${{ secrets.DOCS_SYNC_PR_TOKEN || secrets.OPENHANDS_BOT_PAT || secrets.GH_TOKEN || github.token }} 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,6 +59,7 @@ jobs: if: steps.detect_changes.outputs.changes == 'true' uses: peter-evans/create-pull-request@v7 with: + token: ${{ env.CREATE_PR_TOKEN }} commit-message: | docs(sync): code blocks from agent-sdk From c5bc291b18443b39da481330c1ec9e3398dc8a5e Mon Sep 17 00:00:00 2001 From: enyst Date: Sat, 25 Oct 2025 16:57:06 +0000 Subject: [PATCH 4/4] =?UTF-8?q?ci:=20align=20sync=20workflows=20with=20exi?= =?UTF-8?q?sting=20repo=20pattern\n\n-=20Keep=20peter-evans/create-pull-re?= =?UTF-8?q?quest=20default=20token=20usage=20(no=20PAT)\n-=20Explicitly=20?= =?UTF-8?q?checkout=20main=20so=20manual=20runs=20don=E2=80=99t=20operate?= =?UTF-8?q?=20in=20PR=20context\n-=20No=20other=20logic=20changes\n\nCo-au?= =?UTF-8?q?thored-by:=20openhands=20?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/sync-agent-sdk-openapi.yml | 3 --- .github/workflows/sync-docs-code-blocks.yml | 4 ---- 2 files changed, 7 deletions(-) diff --git a/.github/workflows/sync-agent-sdk-openapi.yml b/.github/workflows/sync-agent-sdk-openapi.yml index 91e6d1a8..548723a1 100644 --- a/.github/workflows/sync-agent-sdk-openapi.yml +++ b/.github/workflows/sync-agent-sdk-openapi.yml @@ -21,8 +21,6 @@ jobs: env: # GITHUB_TOKEN is fine. GH_CLONE_TOKEN: ${{ secrets.GITHUB_TOKEN }} - # Token used for creating PRs. Prefer a PAT secret if available. - CREATE_PR_TOKEN: ${{ secrets.DOCS_SYNC_PR_TOKEN || secrets.OPENHANDS_BOT_PAT || secrets.GH_TOKEN || github.token }} # For workflow_dispatch this will be set; for push/schedule it will fall back to main. AGENT_SDK_REF: ${{ github.event.inputs.agent_sdk_ref || 'main' }} @@ -75,7 +73,6 @@ jobs: if: steps.detect_changes.outputs.changes == 'true' uses: peter-evans/create-pull-request@v7 with: - token: ${{ env.CREATE_PR_TOKEN }} commit-message: | docs(sync-openapi): agent-sdk ${{ env.AGENT_SDK_REF }} diff --git a/.github/workflows/sync-docs-code-blocks.yml b/.github/workflows/sync-docs-code-blocks.yml index c9926166..3fa7d054 100644 --- a/.github/workflows/sync-docs-code-blocks.yml +++ b/.github/workflows/sync-docs-code-blocks.yml @@ -18,9 +18,6 @@ permissions: jobs: sync-code-blocks: runs-on: ubuntu-latest - env: - # Prefer a PAT if available to create PRs, then fall back to GITHUB_TOKEN - CREATE_PR_TOKEN: ${{ secrets.DOCS_SYNC_PR_TOKEN || secrets.OPENHANDS_BOT_PAT || secrets.GH_TOKEN || github.token }} steps: - name: Checkout docs repository (main) uses: actions/checkout@v4 @@ -59,7 +56,6 @@ jobs: if: steps.detect_changes.outputs.changes == 'true' uses: peter-evans/create-pull-request@v7 with: - token: ${{ env.CREATE_PR_TOKEN }} commit-message: | docs(sync): code blocks from agent-sdk