I have written the same shell loop more times than I'd like to admit. Call the API, check whether the PR has a review yet, sleep 30, try again. Every version looks slightly different and every one is a little bit wrong: too chatty, too slow, or missing an exit condition, so it spins until the job timeout kills it. So when GitHub said its CLI can now wait for a pull request to change "with a single command instead of polling it in a loop", I read the changelog twice.
Starting with gh v2.105.0, GitHub CLI supports GitHub Event Streams through a new gh event listen command. Before you rewrite anything, know that it is in preview and sits behind a waitlist.
What landed in v2.105.0
You give gh event listen a pull request URL and the events you care about. Per the GitHub Changelog, it creates a subscription, opens the stream and prints each event as a line of JSON.
The events it covers:
- submitted reviews
- pull request state and head changes
- merge conflicts
- completed check suites
By default the command exits after the first event. Three flags change that. --count waits for more than one event, --follow keeps listening, and --timeout stops waiting after a duration you set. You can trim the output with --jq or --template, the same filtering flags you already use elsewhere in gh.
Subscriptions are also manageable directly, with gh event subscription create, list, view and delete.
Why the exit-on-first-event default is the good part
The default looks small, but it's the reason I'm excited. A command that blocks and then exits is easy to compose. In a shell script or a CI step, "wait until something happens, then carry on" is the whole control flow, and you no longer have to pick a sleep interval.
Think about what you do today while a PR waits on review. Either something polls, burning API calls and adding up to one full interval of lag before it notices, or a human keeps refreshing the tab. Neither is how anyone wants to spend an afternoon.
GitHub is also aiming this at agents. According to the changelog, 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 coding agent driving the CLI should find the command without you writing it into a prompt. If you've watched an agent poll a PR for an hour, you'll feel this one.
Trying it in a script
The changelog doesn't print an example invocation, so I won't guess at the exact event names. gh event --help lists them. The shape of a CI step is roughly this:
# Block until the PR changes, give up after a bounded wait,
# and keep only the fields the next step needs.
gh event listen "$PR_URL" <events...> \
--timeout <duration> \
--jq '<filter>'
Swap the placeholders for the event names and duration format from gh event --help. For a bot that reacts to every review on a long-lived PR, --follow is the mode you want. For a step that should wait for exactly two things, use --count.
Rough edges to check before you delete your loops
Preview means preview. GitHub says the gh event commands may change, and access requires Event Streams, which is itself in preview on GitHub.com. You have to join the waitlist before any of this works for you. Keep your polling fallback in place until your account has access and the flags stop moving.
Always set --timeout in CI. A blocking wait without a bound turns a quiet PR into a runner that sits idle until the job-level timeout ends it, and nobody enjoys debugging a step that just never returned.
Be deliberate about which events you pass. With the default, the first matching event ends the command. If you subscribe to reviews and check suites together and a review comes in first, your script moves on before CI has finished.
Watch your subscriptions too. gh event listen creates one, and the changelog doesn't say what happens to it once the command exits. Run gh event subscription list after a few test runs so you know whether stale ones are piling up.
How we've been waiting until now
Most of us already have one of three setups. There's the hand-rolled gh api loop with a sleep, which needs nothing extra and is wasteful in exactly the ways described above. gh pr checks --watch and gh run watch cover the specific case of waiting on CI, but not a review or a merge conflict. Then there are webhooks, the classic push model. They are efficient, but you need a reachable endpoint to receive them, which is awkward from a laptop, a short-lived CI job or a sandboxed agent.
gh event listen sits between those. You get push delivery, and the client opens the connection, so there's nothing to host.
My verdict is to try it once you're off the waitlist, but give it time before betting a merge queue on it. What I'm watching next is whether Event Streams grows beyond pull requests. A single blocking wait on a workflow run, a release or a deployment would let me delete a lot more sleep loops.
Top comments (0)