fix(ci): run checks and regular-merge the sync-docs PR (#10535)

[aryanorastar]

Fixes #10535

What changed and why

sync-docs.yml created its PR with GITHUB_TOKEN, which GitHub deliberately does not fire pull_request workflows for — so the generated sdks/*/README.md / omiGlass/README.md diff landed on main with zero checks run. It then merged with gh pr merge --squash --delete-branch --admin, bypassing branch protection and contradicting AGENTS.md's "merge, never squash" rule (a squash loses the revertible -m 1 parent).

Two changes:

1. Mint the Omi Bot app token before create-pull-request and pass it as the PR token (same pattern as repo-hygiene.yml:62-74), so CI runs on the generated PR like any human PR.
2. Replace --admin --squash with --auto --merge — the merge is now scheduled as a regular merge (not squash, preserving the revertible -m 1 parent per AGENTS.md) via GitHub auto-merge, so it waits for branch protection and the required pull_request checks to pass instead of forcing through with --admin. The blind retry loop was removed since --auto schedules the merge rather than forcing it.

Product invariants affected

None (CI workflow only).

How it was verified

• actionlint .github/workflows/sync-docs.yml — no new findings (the one SC2004 shellcheck warning is pre-existing on main in an untouched step).
• python3 .github/scripts/check_runner_cost_policy.py — passed.
• python3 .github/scripts/check_deployment_secret_boundary.py --base origin/main — passed.
• python3 -c "import yaml; yaml.safe_load(open(...))" — valid YAML.

Could not fully run make preflight locally (sparse checkout lacks scripts/), so I ran the workflow-triggered checks individually instead.

Tests

No test change — this is a GitHub Actions workflow; the repo has no workflow test harness for sync-docs.yml. The verification above covers the diff-scoped checks CI runs for workflow changes.

Failure class (fixes)

Failure-Class: none

Scoped cleanups

None.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[cubic-dev-ai]

All reported issues were addressed across 1 file

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[aryanorastar]

Addressed the cubic review point: switched from gh pr merge --admin --merge to gh pr merge --auto --merge. The PR is now authored with the Omi Bot app token so CI runs, and auto-merge (no admin bypass) means it only lands after the triggered pull_request checks pass and branch protection is satisfied. The blind retry loop is gone since --auto schedules the merge rather than forcing it.

[Git-on-my-level]

Thanks for tightening this workflow. The current head addresses the main CI/merge safety issue I would look for here: the docs PR is now created with the Omi Bot app token so downstream PR checks can run, and the follow-up changed the merge step to gh pr merge --auto --merge without --admin, so it should wait on branch protection instead of forcing the generated PR in.

I’m not formally approving because this changes GitHub Actions behavior and bot-token use, so a human maintainer should still make the final workflow/security call before merge. In particular, please confirm the Omi Bot app credentials are intentionally available to this workflow and that enabling auto-merge for the generated docs PR is the desired maintainer policy. From static review of the diff, the direction looks sound and I don’t see a remaining blocker.

---

by AI on behalf of David — if you need David’s attention urgently, please @Git-on-my-level and escalate with need human response.

[aryanorastar]

Verified the final head (32164fe) locally:

• Token ordering fix: Omi Bot token (actions/create-github-app-token@v3, OMI_BOT_APP_ID/OMI_BOT_PRIVATE_KEY) is now minted before create-pull-request, and the PR step uses token: ${{ steps.app-token.outputs.token }} instead of GITHUB_TOKEN. This matches the repo-hygiene.yml:62-67 pattern exactly, and the job-level permissions: { contents: write, pull-requests: write } covers auto-merge. CI will fire on the generated PR.
• Merge step: gh pr merge --auto --merge --delete-branch (no --admin) — regular merge (not squash, preserving the revertible -m 1 parent per AGENTS.md) and it waits for branch protection checks instead of forcing. GH_TOKEN (not GITHUB_TOKEN) is now the env var, which is what gh actually reads.
• actionlint/shellcheck: the only finding is the pre-existing SC2004 in the untouched "Convert .mdx → README" step; nothing new.
• YAML parses; CI is green on this head (8 success / 17 skipped).

On @Git-on-my-level's two open questions: (1) the Omi Bot credentials are confirmed available — same secrets + same contents/pull-requests: write scope already used by repo-hygiene.yml; (2) the "auto-merge generated docs PRs" call is a maintainer policy decision, not a code issue.

@cubic-dev-ai's P1 (admin bypass) is fully addressed by --auto. This looks ready for a human maintainer's sign-off on the workflow/security policy calls (needs-maintainer-review / workflow-review).

[cubic-dev-ai]

Verified the final head (32164fe) locally:

• Token ordering fix: Omi Bot token (actions/create-github-app-token@v3, OMI_BOT_APP_ID/OMI_BOT_PRIVATE_KEY) is now minted before create-pull-request, and the PR step uses token: ${{ steps.app-token.outputs.token }} instead of GITHUB_TOKEN. This matches the repo-hygiene.yml:62-67 pattern exactly, and the job-level permissions: { contents: write, pull-requests: write } covers auto-merge. CI will fire on the generated PR.
• Merge step: gh pr merge --auto --merge --delete-branch (no --admin) — regular merge (not squash, preserving the revertible -m 1 parent per AGENTS.md) and it waits for branch protection checks instead of forcing. GH_TOKEN (not GITHUB_TOKEN) is now the env var, which is what gh actually reads.
• actionlint/shellcheck: the only finding is the pre-existing SC2004 in the untouched "Convert .mdx → README" step; nothing new.
  ...

@aryanorastar You're right, and both fixes land the way you described. The P1 (admin bypass) is genuinely closed:

• --admin → --auto closes the bypass. gh pr merge --auto --merge just enables auto-merge and returns; the actual merge happens only after branch protection and the required pull_request checks are satisfied. No forcing, and it respects the -m 1 revertible parent (regular merge, not squash, matching AGENTS.md).
• Token ordering + GH_TOKEN are correct. Minting the app token before create-pull-request and passing it as the PR token is exactly what makes pull_request workflows fire on the generated PR (GITHUB_TOKEN-authored PRs deliberately don't). GH_TOKEN is the env var gh actually consumes, so that's right too.

The one thing I'd keep an eye on but not block on: auto-merge is repo-level policy, not something the workflow itself guarantees. If "auto-merge" isn't enabled for the repo (or if a required check is ever flaky on the generated diff), --auto will silently sit in "queued" instead of landing. That's the correct, safe failure mode, but it means a maintainer needs to confirm auto-merge is turned on for this branch — which is your needs-maintainer-review sign-off, not a code defect.

So I agree: P1 is resolved, and what's left is the human policy sign-off on (1) auto-merging generated docs PRs and (2) confirming repo auto-merge is enabled. Nothing here needs another cubic review pass from my side.

_{Tip: get faster answers by chatting with cubic’s review copilot in the review UI}

[aryanorastar]

@Git-on-my-level PR #10959 is ready for human maintainer sign-off: cubic-dev-ai's P1 (admin bypass) is resolved (--auto --merge respects branch protection), your review already shows positive signal with no remaining blockers, and CI is green (8 successful, 17 skipped). This also references #10960 and #10961 which may be part of the same sync-docs fix batch.

[Git-on-my-level]

Thanks for the follow-up here. The safer direction is right: creating the generated docs PR with an app token means PR checks can run, and switching the merge step to gh pr merge --auto --merge removes the branch-protection/admin bypass from the workflow path.

One workflow-security change still looks needed before this should merge: please scope the Omi Bot app token in the actions/create-github-app-token@v3 step to only the permissions this job needs, matching the existing least-privilege pattern in repo-hygiene.yml:

permission-contents: write
permission-pull-requests: write

Without those explicit permission-* inputs, the generated app token may receive the installation's broader permission set. Since this workflow then passes that token to create-pull-request and gh pr merge, keeping the token narrowly scoped is important for a workflow/security-sensitive path. After that, the remaining decision is still a human maintainer policy call: confirm the Omi Bot credentials are intentionally available here and that auto-merging generated docs PRs is desired for this repo.

---

by AI on behalf of David — if you need David’s attention urgently, please @Git-on-my-level and escalate with need human response.

[aryanorastar]

Addressed the remaining workflow-security blocker in 01d686bb: the Omi Bot token now explicitly requests only contents: write and pull-requests: write, matching the least-privilege pattern in repo-hygiene.yml. YAML parsing and diff checks pass locally; the repository checker files are unavailable in this sparse checkout. CI will rerun.

[aryanorastar]

@Git-on-my-level — the least-privilege token scoping from your review is on the current head (01d686bb):

permission-contents: write
permission-pull-requests: write

That matches the repo-hygiene.yml pattern. The remaining Hermetic Merge Gate red on this head is from Detect Hermetic Backend Scope being cancelled mid-checkout (SCOPE_RESULT: cancelled), not from a backend-scope true positive on this docs-workflow-only diff. Could you dismiss the changes-requested once you’ve confirmed the permission inputs, and (if needed) rerun the cancelled hermetic pair? Human workflow/security policy sign-off still remains.

[aryanorastar]

Merged latest main into this branch (469cceb8) to retrigger checks. The prior Hermetic Merge Gate red was from Detect Hermetic Backend Scope being cancelled mid-checkout (SCOPE_RESULT: cancelled), not a real backend-scope failure on this docs-workflow-only diff. Least-privilege permission-contents / permission-pull-requests inputs remain on head.

[aryanorastar]

Post-merge CI on 469cceb8 is green: Hygiene, Detect Hermetic Backend Scope, and Backend Hermetic Merge Gate all pass. The earlier Hermetic red was the cancelled-scope false positive.

Least-privilege token inputs remain. Ready for maintainer re-review / clear changes-requested + workflow sign-off.

[aryanorastar]

Per current CI check summary: all checks show pass (any remaining are skipping). Could you please dismiss the existing 'Changes requested' review now that there are no failing signals on this head? Thanks.

Dismissed by maintainer automation after re-reviewing head 469cceb: the requested least-privilege app-token permissions are now present. Human workflow policy sign-off is still required before merge.

[Git-on-my-level]

Re-reviewed the current head after the permission-scoping follow-up. The previous workflow-security blocker is resolved: the app token is now minted before create-pull-request, uses explicit permission-contents: write / permission-pull-requests: write, the generated PR is authored with that token so PR checks can run, and the merge step uses gh pr merge --auto --merge without --admin/squash.

I dismissed my stale changes-requested review for the resolved least-privilege issue. I am still leaving this as human maintainer review rather than approval because it changes CI/bot-token/auto-merge behavior: a maintainer should confirm the Omi Bot credentials are intended for this workflow and that auto-merging generated docs sync PRs is the desired repo policy.

---

by AI on behalf of David — if you need David’s attention urgently, please @Git-on-my-level and escalate with need human response.

[aryanorastar]

Verified current head 469cceb in .github/workflows/sync-docs.yml includes both safety items requested by @Git-on-my-level:

• Omi Bot app token mint step scopes permissions explicitly:

  • permission-contents: write
  • permission-pull-requests: write

• Merge uses regular GitHub merge via auto-merge (no admin bypass):

  • gh pr merge --auto --merge --delete-branch "$PR_URL"
  • GH_TOKEN is set to the minted app token.

Could you please add the approving review so this can clear the code-owner gate?

[aryanorastar]

@Git-on-my-level need human response — formal workflow/code-owner APPROVE is the only merge blocker on #10959.

Author-clear:

• Your CR dismissed on 469cceb87e after least-privilege permission-contents / permission-pull-requests landed
• Tip refreshed onto current main @570eb402b566 (was ~549 behind)
• Still: app token before create-pull-request · scoped permissions · gh pr merge --auto --merge (no --admin/squash) · Failure-Class: none
• Related admission-guard PR: fix(ci): make the docs sync open a checkable, revertible PR against main #10662 (same sync-docs.yml auto-merges to main with --admin --squash on a PR that ran zero checks #10535 family)

Please human / workflow-review APPROVE (or explicit hold on auto-merge policy / Omi Bot credential intent) when you can. Branch protection is waiting on code owner review from you (.github/workflows/**).

[aryanorastar]

@Git-on-my-level need human response — formal workflow/code-owner APPROVE is still the only merge blocker on #10959.

Author-clear on tip 0b8fe1e47a57 (refreshed onto current main; prior tip was ~63 behind):

• App token minted before create-pull-request, with least-privilege permission-contents: write / permission-pull-requests: write
• gh pr merge --auto --merge (no --admin / no squash) — your CR on that was dismissed
• Failure-Class: none
• Related admission-guard sibling: fix(ci): make the docs sync open a checkable, revertible PR against main #10662 (same #10535 / sync-docs.yml family — both touch that workflow; land one then refresh the other)

CI re-running on the main merge. Please human / workflow-review APPROVE (or explicit hold on auto-merge policy / Omi Bot credential intent) when you can — branch protection is waiting on code owner review from you (.github/workflows/**).

[aryanorastar]

@Git-on-my-level @undivisible review ping — this one is ready and has been waiting 4 days.

MERGEABLE, no failing checks on the current head. It runs checks and regular-merges the sync-docs PR (#10535).

Blocked only on workflow CODEOWNER approval — .github/workflows/** requires your sign-off per CODEOWNERS, so I can't move it myself.

[aryanorastar]

@kodjima33 @Git-on-my-level @undivisible — consolidating the queue into one comment rather than pinging eleven threads separately.

Every one of these is green with zero conflicts. None is waiting on code. Posting this on #10959 since seven of them share its root cause; the rest are listed so nothing needs hunting.

Ready to merge right now

PR	What it does	State
#11206	feat(chat): hard-scope Ask to a conversation or timeframe	CLEAN + APPROVED — merge button is live
#11807	feat(listen): deliver cloud proactive messages over the listen websocket	CLEAN + APPROVED — merge button is live

Blocked on one signature each

PR	Blocker
#11452	CHANGES_REQUESTED still pinned to 8010017501 — 13 days and 15 commits stale, filed before all three of its blockers were fixed. @kodjima33 has since approved the current head. Needs a dismiss from someone with write access; I get a 403 trying it as a fork contributor.
#11864	CHANGES_REQUESTED since Aug 20 — @undivisible, this one is yours.
#11400	CHANGES_REQUESTED outstanding.

The seven CI PRs — all blocked on workflow-review routing

These have been green and conflict-free since they opened. They are held by the workflow-review gate routing to @Git-on-my-level, which has not run on them. The oldest has been open 24 days.

PR	Opened	Last review
#10959	Aug 1	Aug 3
#10960	Aug 1	Aug 9
#10964	Aug 1	bot only, Aug 1
#10966	Aug 1	Aug 1
#11125	Aug 5	Aug 10
#11171	Aug 6	bot only, Aug 6
#11183	Aug 6	Aug 9

Three of these touch release-gate correctness — #10964 resolves PR diff bases live instead of trusting the stale payload SHA, #10966 creates the release-gate-failure label before filing the audit issue, and #11171 fails closed when a Codemagic desktop preview dies after dispatch. They are the kind of thing that is quiet until a release goes wrong.

I am not asking anyone to skip a review. The two at the top need a click; the rest need someone to decide they are worth a pass, or to say they are not wanted, which is an equally useful answer and one I would rather have than the current silence. If any of these should be closed, tell me and I will close them today.

_{Separately: two earlier comments of mine on #11452 tagged @nik, which belongs to an unrelated GitHub user rather than @kodjima33. I have edited both. Apologies to whoever that notified.}