docs(agents): draft-then-ready PR creation prevents the merge-ref CI race#110970
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: fe1994f832
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - GH comments with backticks, `$`, or shell snippets: use heredoc/body file, not inline double-quoted `--body`. | ||
| - PR create: real body required. Use the current template: `What Problem This Solves`, `Why This Change Was Made`, `User Impact`, and `Evidence`; include visible refs, behavior, and validation. | ||
| - PR create races GitHub's merge-ref computation: the pull_request-open CI run can drop entirely or die as `startup_failure`/`BuildFailed` (`(Unknown event)`, not rerunnable). After opening, verify the CI workflow attached to the head SHA; if missing, close/reopen the PR to re-fire the event. | ||
| - PR create races GitHub's merge-ref computation: the pull_request-open CI run can drop entirely or die as `startup_failure`/`BuildFailed` (`(Unknown event)`, not rerunnable). Prevention: `gh pr create --draft`, poll `mergeable` non-null, then `gh pr ready`. After opening, verify the CI workflow attached to the head SHA; if missing, the hourly `pr-ci-sweeper` re-fires it, or close/reopen manually. |
There was a problem hiding this comment.
An agent following this guidance is likely to use gh pr view --json mergeable, but that command exposes GraphQL's non-null MergeableState enum (MERGEABLE, CONFLICTING, or UNKNOWN), not the REST API's nullable boolean (GitHub contract). During the merge-ref race it therefore returns the non-null value UNKNOWN, so a literal “poll until non-null” completes immediately and gh pr ready can reintroduce the dropped-CI race this line is intended to prevent. Specify an exact REST gh api poll for .mergeable != null, or tell GraphQL users to wait until the value is not UNKNOWN.
Useful? React with 👍 / 👎.
|
Merged via squash.
|
1 participant
What Problem This Solves
The AGENTS.md note from #110812 documents the dropped PR-open CI race and its manual remedy, but not the validated prevention or the now-landed automated repair (#110889/#110945).
Why This Change Was Made
Draft-then-ready was validated twice this week: creating the PR as a draft, polling
mergeableuntil non-null, then marking ready makes CI attach first try (ready_for_reviewis in ci.yml's trigger types and the draft preflight skips cheaply). The sweeper reference tells agents the self-heal path exists before they reach for manual close/reopen.User Impact
Agent-workflow guidance only; no runtime changes.
Evidence
Docs-only:
git diff --checkclean. This PR is itself created non-draft immediately after push, deliberately racing the merge ref as a live test of the sweeper's repair path.