Chore/nightly sync prs

[enyst]

This PR proposes to run the sync workflows on a schedule, rather than mixing in unrelated PRs

Related slack report

• Removes push triggers from sync-docs-code-blocks and sync-agent-sdk-openapi to avoid running on unrelated PRs.
• Switches both workflows to use peter-evans/create-pull-request to open dedicated, reusable PRs (chore/sync-docs-code-blocks and chore/sync-openapi).
• Limits OpenAPI sync scope to openapi/agent-sdk.json.
• Updates SDK CI guidelines to reflect the new schedule and PR flow.

Outcome: reduced PR noise, no piggyback commits, and easier reverts.

[openhands-ai]

Looks like there are a few issues preventing this PR from being merged!

• GitHub Actions are failing:
  • Sync agent-sdk OpenAPI

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #51 at branch `chore/nightly-sync-prs`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}

[enyst]

@OpenHands I ran sync-openapi with manual workflow trigger, on this PR branch, and it didn't work

sync-openapiGitHub Actions is not permitted to create or approve pull requests. - https://docs.github.com/rest/pulls/pulls#create-a-pull-request
--

Annotations
1 error
[sync-openapi](https://github.com/OpenHands/docs/actions/runs/18804689788/job/53657025882#step:8:120)
GitHub Actions is not permitted to create or approve pull requests. - https://docs.github.com/rest/pulls/pulls#create-a-pull-request

Please think deeply and fix this.

[openhands-ai]

I'm on it! enyst can track my progress at all-hands.dev

[openhands-ai]

Summary of work completed

What I changed

• Fixed the failing “GitHub Actions is not permitted to create or approve pull requests” error by ensuring the sync workflows create PRs using a PAT if available, and by running them against main rather than the PR branch.
• Updated two workflows:
  1. .github/workflows/sync-agent-sdk-openapi.yml
     • Checkout the docs repo at ref: main to avoid PR-branch context.
     • Added CREATE_PR_TOKEN env, which prefers a PAT:
       ${{ secrets.DOCS_SYNC_PR_TOKEN || secrets.OPENHANDS_BOT_PAT || secrets.GH_TOKEN || github.token }}
     • Passed token: ${{ env.CREATE_PR_TOKEN }} to peter-evans/create-pull-request.
  2. .github/workflows/sync-docs-code-blocks.yml
     • Checkout the docs repo at ref: main.
     • Added the same CREATE_PR_TOKEN env and passed it to the create-pull-request step.

Why this fixes your issue

• When manually triggered from a PR branch, the default GITHUB_TOKEN is restricted and can’t create PRs. By:
  • Forcing the workflows to operate on main, and
  • Supplying a PAT (if present) to create-pull-request,
    the workflows can open the dedicated chore/* sync PRs without hitting permissions errors. If no PAT is configured, the workflows fall back to the default token, which will still work if you’ve enabled “Allow GitHub Actions to create and approve pull requests” in repo settings.

What you may need to do

• Preferred: Add a repo/org secret containing a PAT with repo scope named DOCS_SYNC_PR_TOKEN (recommended), or OPENHANDS_BOT_PAT, or GH_TOKEN.
• Alternative: Enable “Allow GitHub Actions to create and approve pull requests” in Settings → Actions → General → Workflow permissions.

Checks

• Request addressed: Yes
  • Root cause identified and explained
  • Workflows updated to avoid restricted PR context and to use a proper token for PR creation
• Changes concise: Yes
  • Only touched the two relevant workflow files, minimal additions
• Changes pushed: Yes
  • Commit 360d7c0 on branch chore/nightly-sync-prs

Next steps

• Add the PAT secret or enable the repo setting, then re-run the “Sync agent-sdk OpenAPI” workflow (or the code blocks sync). The workflow should now open/update its dedicated chore/sync-* PRs successfully.

_{View full conversation}