Latest in AI
GitHub CLI Event Streams: Wait for PR Changes Without a Polling Loop
Use gh event listen to wait for reviews and checks, while handling missed events, timeout exit codes and the difference between an event and permission to merge.
An agent that keeps asking whether a pull request has changed is doing unnecessary work. But replacing that loop with an event listener creates a different risk: treating the next notification as a complete picture of the pull request.
GitHub CLI now provides a better way to wait. The important implementation detail is what you do after the wait ends. I would use events to wake the workflow, then fetch the current state before deciding what happens next.
Check preview access before changing your script
GitHub introduced Event Streams support in CLI version 2.105.0. The commands are in preview and require Event Streams access through its waitlist. Upgrading the CLI alone does not grant that access.
The command can wait for reviews, pull request state or head changes, merge conflicts and completed check suites. By default it exits after one event; count, follow and timeout options support other waiting patterns. Read the November 18 announcement.
For an initial rollout, I would replace one well-understood polling loop rather than every background check. Keep the old workflow available until you know how the new one behaves with your account and runner.
Start with a bounded review wait
This is documented command syntax, with a placeholder pull request URL:
gh event listen \
--resource https://github.com/OWNER/REPO/pull/123 \
--event com.github.pull_request.review.submitted.v1 \
--timeout 30m
The CLI emits one CloudEvent JSON object per line on stdout; status messages go to stderr. A timeout exits with status 8. Events contain a data.api_url pointing to the changed object. The feature supports github.com pull requests, not GitHub Enterprise Server or GHE.com. Check the CLI manual.
I have not run this example against an authorized preview account. Replace the placeholder, confirm access and test it on a pull request where waiting has no production consequence.
Close the gap between checking and listening
The manual warns that earlier events are not replayed. Read the current pull request state after the stream reports that it has attached, even if you checked before starting it. Reconnection can also miss events that occurred while disconnected. Read the delivery caveats.
My proposed workflow is to establish the listener, take a fresh state snapshot, and reconcile that snapshot with the condition you actually care about. If the condition is already satisfied, there is no reason to keep waiting for another notification.
For example, your agent might check a pull request, see no review and then start listening. A reviewer could submit feedback between those steps. Treating the first check as authoritative could leave the agent waiting unnecessarily.
Keep the state check outside the model's guesswork. Record which pull request and head revision the workflow evaluated.
Do not mistake one completed check for a green PR
A pull request can have several check suites. Each completed suite can emit its own event; the manual recommends reading pull request checks after notifications, for example with gh pr checks. See check-suite behavior.
My decision rule would be more specific than “a check finished.” Define which required checks must pass, which head revision they must cover and what should happen if that revision changes.
The same distinction applies to reviews. A submitted review might request changes rather than approve them. Even approval is not, by itself, authorization for an agent to merge. Keep repository protections and your team's human approval requirements intact.
Handle timeouts as an unresolved wait
I would give timeout, connection failure and a qualifying state change different outcomes in the surrounding workflow. A timeout means the waiting period ended, not that the pull request passed or failed review.
Before retrying, fetch the current state. Then choose between another bounded wait and handing the unresolved item back to its owner. Avoid launching a new listener repeatedly without accounting for the previous one.
For a long-running workflow, retain enough context to resume safely: the pull request URL, expected condition, last evaluated revision and next review time. An event is useful as a notification, but it should not be the only record of why the workflow continued.
Test the awkward transitions
My suggested pilot includes a review submitted during listener startup, a head update while checks are running, a timeout with no changes and a disconnection followed by recovery.
These are proposed acceptance tests, not results I have measured. The useful outcome is that the agent reaches the right decision after each transition, not merely that it receives JSON.
Event-driven waiting can remove a noisy polling loop. Reliable automation still depends on rechecking the current state and acting only within the workflow's existing authority.
I'm Paras. I work at the intersection of AI, engineering and distribution.
I help AI and developer-tool teams explain technical workflows through clear writing and practical storytelling.