Stop Polling Pull Requests: A Safe Start with GitHub Event Streams

Use GitHub CLI event streams to wait for pull-request changes without polling loops, while handling missed, duplicate, and expired events.

Developer Tools•~7 min read•November 19, 2026•By QZ-L Editorial
#GitHub#GitHub CLI#Coding Agents#Automation
Looking for related guides? Start with the qz-l Learning Center and explore more tutorials in this topic cluster.

Stop Polling Pull Requests: A Safe Start with GitHub Event Streams

Many scripts and coding agents need to wait for a pull request to change. They wait for a review, a push, a merge, or a check run to finish. The familiar solution is a loop:

  1. Fetch the pull request.
  2. Sleep for a few seconds.
  3. Fetch it again.
  4. Repeat until something looks different.

That works, but it is a blunt synchronization mechanism. It creates unnecessary API traffic, adds a polling delay, and still leaves the script responsible for deciding how often to check and what happens when the state changes between requests.

GitHub Event Streams introduce a more direct preview API: subscribe to a pull request, keep an HTTP Server-Sent Events (SSE) connection open, and receive a notification when a selected kind of change occurs. GitHub CLI 2.105.0 adds a convenient wrapper, gh event listen, so a local script or agent can wait without implementing the subscription and stream protocol itself.

The important qualification is that this is a notification stream, not a durable queue. Events can be missed, duplicated, or delivered out of order. A reliable consumer still fetches the current pull-request state after it attaches and after relevant events.

What the new command does

The command takes a pull request URL and one or more event types. For example, this waits up to 30 minutes for the next submitted review:

gh event listen \
  --resource https://github.com/OWNER/REPO/pull/123 \
  --event com.github.pull_request.review.submitted.v1 \
  --timeout 30m

By default, the command exits after the first event. That makes it useful in an agent step: the command blocks while nothing has changed, then returns control to the caller. Use --count N for several events or --follow for a long-lived listener. --jq and --template can reduce each JSON event to the field a script needs.

The available pull-request events are:

  • com.github.pull_request.review.submitted.v1
  • com.github.pull_request.state.changed.v1
  • com.github.pull_request.head.changed.v1
  • com.github.pull_request.merge_conflict.v1
  • com.github.pull_request.check_suite.status.changed.v1

For example, a merge-or-close wait can be bounded like this:

gh event listen \
  --resource https://github.com/OWNER/REPO/pull/123 \
  --event com.github.pull_request.state.changed.v1 \
  --timeout 45m

The timeout is more than a convenience. A process that waits forever can strand a worker, terminal session, or agent run. The CLI exits with status 8 when the timeout wins, so callers should distinguish “no event arrived yet” from a command or authentication failure.

Treat an event as a hint, not as the final state

An event tells you that something changed. It is not necessarily a complete snapshot of the pull request, and most event types do not state the final outcome in the event itself. Each event includes data.api_url, which points to the pull request, review, or check suite that changed.

That leads to a safer pattern:

start listening
wait until the stream reports that it is attached
fetch the current pull-request state
wait for an event
fetch the resource identified by data.api_url
reconcile the current state
repeat or finish

The initial fetch matters because the stream does not replay history. A review or push that happened before the stream opened is not delivered to a new listener. GitHub’s documentation also warns that a short window around subscription creation and periods of disconnection can leave gaps.

The follow-up fetch matters because events can be duplicated or arrive out of order. Suppose a pull request receives two pushes quickly. A consumer that assumes event order may process stale information last. A consumer that refetches the pull request and compares its current head commit can converge on the truth instead.

For check suites, the event contains a conclusion such as success or failure, but one pull request can have several check suites. There is no single event meaning “all checks are complete.” After a check-suite event, query the pull request’s checks and apply your own policy. If required checks use commit statuses rather than check suites, query those separately as well.

A practical agent wrapper

An agent or shell script can use the CLI as a wake-up mechanism and then perform an authoritative read. This example is intentionally a pattern rather than a claimed live test:

set -u

pr_url="https://github.com/OWNER/REPO/pull/123"

if gh event listen \
    --resource "$pr_url" \
    --event com.github.pull_request.review.submitted.v1 \
    --timeout 30m \
    --jq '[.type, .data.api_url] | @tsv'
then
  # Fetch the current review/PR state here.
  gh pr view "$pr_url" --json state,headRefOid,reviews
else
  status=$?
  if [ "$status" -eq 8 ]; then
    printf '%s\n' "No review arrived before the deadline." >&2
  else
    printf 'Event wait failed with status %s.\n' "$status" >&2
    exit "$status"
  fi
fi

The wrapper should not merge a pull request merely because a state-change event arrived. It should fetch the current state, check the repository’s policy, and make the decision from current data. Likewise, a review event should trigger a new review fetch; it should not be treated as approval without checking the review state and the identity of the reviewer.

In a longer-running consumer, store a small deduplication key such as the event ID or the API URL plus the resource version you have processed. Still refetch state: deduplication prevents repeated work, but it does not repair a missed event.

What happens under failure?

The CLI reconnects if the event stream breaks, but events that occur while disconnected are not delivered. The command can recreate an expired subscription when it needs to reconnect, according to the CLI documentation. A custom SSE client must implement more of this lifecycle itself:

  • Ignore SSE heartbeat comment lines.
  • Reconnect after an unexpected disconnect.
  • Refresh an installation token before reconnecting if it may have expired.
  • Handle the terminal github.stream.end event and its outcome.
  • Back off with jitter rather than reconnecting in a tight loop.
  • Fetch current state after reconnecting.

Subscriptions expire after 24 hours, and each user, app, or installation token can have at most 100 active subscriptions. gh event listen does not delete a subscription when it exits. Short-lived waits can therefore leave subscriptions until they expire; a service that creates many listeners should list and delete subscriptions deliberately.

The stream is also not a webhook replacement in every environment. It does not require a public endpoint, which is useful for developer machines and local agents, but the preview currently supports pull requests on GitHub.com only. It is not available on GHE.com or GitHub Enterprise Server. Access is being rolled out through a wait list, and the token must be a supported user or GitHub App installation token with read access to the pull request.

When to keep polling

Event Streams are a good fit when a process is already waiting for a pull request and can react to a notification. They are not a reason to remove every periodic reconciliation job. Keep a bounded fallback when:

  • the account does not have Event Streams access;
  • the repository is on an unsupported GitHub host;
  • the workflow needs commit statuses or conversation-tab comments that do not emit supported events;
  • the process must recover from a long outage by scanning current state;
  • the API preview’s limits or change policy are unacceptable for the workload.

A hybrid design can use an event stream for low-latency wake-ups and a slower periodic reconciliation for recovery. The stream reduces needless waiting; the reconciliation protects against the stream’s deliberate lack of replay.

A migration checklist

Before replacing a polling loop, verify:

  1. Upgrade to GitHub CLI 2.105.0 or later, or confirm that the account and API client can use Event Streams.
  2. Confirm preview access and token type before treating a 403 as a transient error.
  3. Choose the narrowest event types that wake the process.
  4. Always use a timeout and handle its exit status.
  5. Treat the first “listening” message as the point after which new events can arrive, then fetch a baseline.
  6. Refetch authoritative state after events; do not infer final state from event order.
  7. Account for duplicate events, disconnect gaps, subscription expiry, and the active-subscription limit.
  8. Keep a recovery path for unsupported event types and missed notifications.

Event-driven waiting is a better primitive than sleeping and repeatedly asking whether a pull request changed, but only when the consumer respects its semantics. Use gh event listen to wake the workflow, use the REST resource to decide what is true, and keep reconciliation close enough to make missed events harmless.

References

Related Posts

Control GitHub Copilot Customizations with Enterprise Managed Settings

Use GitHub Enterprise policies to control Copilot plugins, MCP servers, agents, hooks, and executable extensions without blocking approved tools.

Catch Secrets Before Merge: GitHub's New Copilot Review Path

Use GitHub's preview secret scanning in Copilot security review to catch credentials in code changes before they reach a pull request.

GitHub Actions Workflow Logs: Detect and Respond to Leaked Secrets

Enable GitHub workflow log secret scanning carefully, review preview gaps, and revoke leaked credentials with a practical response checklist.