Playbooks · Coding tasks
Wait for pull requests with gh event listen
Written November 19, 2026
GitHub CLI 2.105 adds gh event listen: wait for a review, a check suite or a merge conflict on a pull request and print it as JSON, instead of polling.
Any script or agent loop that waits on a pull request today does it the wasteful way: ask, sleep, ask again, burning calls the whole time and still reacting late when the answer finally changes. GitHub's changelog post of November 18, 2026 replaces the loop with a wait. GitHub CLI now supports GitHub Event Streams, and with gh v2.105.0 you and your agents can wait for a pull request to change with a single command instead of polling it. The command is in preview, and access to Event Streams sits behind a waitlist — both facts matter before you rebuild a loop around it, and both are covered below.
One command instead of a polling loop
Run gh event listen with a pull request URL and the events you care about, such as a submitted review. The command does the plumbing itself: it creates the subscription, opens the stream, and prints each event as a line of JSON as it arrives. By default it exits after the first event, which is what makes it slot into scripts and agent loops — the wait is a single blocking command that returns the moment the thing you were waiting for happens, carrying the event as structured output your next step can read. Compare the polling version: a loop that wakes on a timer, spends an API call to learn that nothing has changed, and can still be asleep at the moment the review lands.
The flags that shape the wait
Four options cover most shapes of waiting. --count waits for several events before exiting, for a loop that needs, say, two reviews rather than one. --follow keeps listening instead of exiting, which suits a dashboard or a long-running watcher rather than a script step. --timeout stops the wait after a set time, so a pull request that never changes cannot hold a job open forever. And --jq or --template pulls out just the fields you need from each event, so the JSON line that reaches your script is already trimmed to the values it acts on. Between the exit-after-first-event default and these four, most polling loops map onto one command with one or two flags.
What you can wait for
The waitable events cover the moments a pull request workflow actually turns on: submitted reviews, pull request state and head changes, merge conflicts, and completed check suites. A loop can wait for the review, learn from the head change that new commits arrived, stop on a merge conflict, or proceed when the check suite completes. If you want to manage the machinery directly, subscriptions have their own commands: gh event subscription create, list, view and delete. The new commands also surface on their own — gh pr create, gh pr view, gh run view, gh run watch and gh api now suggest gh event listen instead of polling, so a script written with the older habit in mind gets pointed at the replacement.
The catch: preview, and a waitlist
Two gates stand in front of all of this. The gh event commands are in preview and may change, so a loop built on them today may need adjusting as they settle. And they require access to Event Streams, which is itself in preview on GitHub.com — to get access, you sign up for the Event Streams waitlist. Until your access lands, the command cannot run your waits at all. The starting step is mechanical: upgrade to gh v2.105.0 or later, then join the waitlist and wait. The post points to the gh event manual and the Event Streams documentation for the detail, or gh event --help on your own machine.
What to do
- Upgrade first.
gh event listenneeds gh v2.105.0 or later; older installs do not have the command. - Join the waitlist now. Event Streams access gates everything else, and the queue is the slow part — get in it before you need the loop.
- Swap one polling loop as the test. Pick the loop that waits on a single review or check suite, replace it with one blocking
gh event listencall, and keep the polling version until access lands. - Always set a timeout. A wait with no
--timeoutis a job that can hang forever on a pull request nobody touches.
For an agent loop, the default exit-after-first-event is the point: the wait becomes one blocking command instead of a poll cycle, and the event arrives as JSON the loop can act on immediately. But the waitlist gate means a loop cannot depend on it until access lands — so the honest order is upgrade, join the queue, and swap loops one at a time as access arrives. The reviews this command waits for are themselves changing; the page linked below covers Copilot's Adaptive review effort.
Related playbooks
- Hermes Agent 0.23.2 rolls up 1,989 pull requests
- Hermes Agent 0.23.3 rolls up 370 pull requests
- The Nov 16 pull_request_target brownout, in UTC
- GitHub blocks pull_request_target workflows on December 2
Sources
- GitHub Changelog, Wait for pull request events with GitHub CLI —
gh event listenand its first-event exit default, the--count,--follow,--timeout,--jqand--templateoptions, the waitable events, subscription management, the preview status and the Event Streams waitlist, and the gh v2.105.0 requirement.
Back to: Coding playbooks hub · Also: Copilot code review goes Adaptive, checks secrets