Many development workflows need to wait for something to happen on a pull request before continuing. A build automation tool might need to wait for a code review, an updated commit, or the completion of CI checks. An AI coding agent might need to wait for a developer's feedback before making another change.
A common way to handle this is to repeatedly call the GitHub API and check whether the expected change has happened. This approach is known as polling. Although it works, it creates unnecessary API requests and introduces delays between an event occurring and the automation detecting it.
GitHub Event Streams provide another approach. Instead of repeatedly asking GitHub whether something has changed, an integration subscribes to a pull request and receives events when selected changes occur.
This makes it possible to build more responsive automation without maintaining a continuous polling loop. In this article, we will explore how GitHub Event Streams work, how to listen for pull request events using GitHub CLI, and how to use those events in build and automation workflows.
Understanding GitHub Event Streams
GitHub Event Streams allow applications, scripts, and agents to subscribe to changes on a specific resource. When a subscribed event occurs, GitHub sends an event through an open stream.
The current implementation supports pull request events. These include review submissions, new commits, pull request state changes, merge conflicts, and completed check suites.
For example, consider a development workflow with the following steps:
A developer creates a pull request.
An automated process starts reviewing the changes.
The process waits for a developer to submit a review.
Once the review arrives, the process retrieves the latest review information.
Based on the review result, it continues with another validation or notification step.
Without an event stream, the process might check the pull request every few seconds. With Event Streams, it can remain connected and receive an event when the review is submitted.
GitHub uses Server-Sent Events (SSE) to deliver these updates. SSE provides a long-lived HTTP connection through which the server can send events to a connected client.
Unlike traditional webhooks, this approach does not require you to expose a public endpoint that GitHub can call. The client connects to GitHub and listens for updates. This makes it useful for developer machines, command-line tools, and automation agents running in environments where hosting a public webhook endpoint is inconvenient.
How GitHub Event Streams Work
The basic process involves three stages: creating a subscription, opening an event stream, and retrieving the latest resource information.
<escape>### Creating a subscription</escape>
A subscription tells GitHub which pull request you want to monitor and which event types are relevant.
For example, a development tool might subscribe to review submissions and changes to the pull request's head branch.
Opening the event stream
After creating a subscription, the client opens a connection to the stream URL. GitHub sends events as they occur.
The connection can remain open while the automation waits. The client does not need to repeatedly request the pull request's current state.
Retrieving the latest information
An event tells the client that something changed. It also contains an API URL that points to the affected resource.
The client can use that URL to retrieve the latest information through the GitHub REST API.
This separation is important. An event is a notification that something happened, not necessarily a complete description of the change. Your application should retrieve the relevant resource before making important decisions.
Checking the GitHub CLI Requirements
GitHub CLI provides commands for working with Event Streams. The gh event command group includes functionality for listening to events and managing subscriptions.
The Event Streams functionality is currently in public preview and requires access to be enabled for your account. Availability is controlled through a waitlist, so having the correct CLI version alone does not guarantee access.
The GitHub CLI version must be 2.105.0 or later for the new event commands.
Check your installed version:
gh --version
You can also check whether the event commands are available:
gh event --help
Authenticate with GitHub:
gh auth login
Verify your authentication:
gh auth status
The authenticated user or GitHub App installation must have read access to the pull request being monitored. Event Streams supports user tokens and GitHub App installation access tokens. An application authenticating as itself is not supported.
If your account has not been enabled for Event Streams, requests may return a 403 response indicating that event subscriptions are not enabled.
Listening for Pull Request Events
Suppose a development team wants an automation process to wait until someone submits a review on a particular pull request.
You can use gh event listen to wait for that event.
gh event listen \
--resource https://github.com/OWNER/REPO/pull/123 \
--event com.github.pull_request.review.submitted.v1 \
--timeout 30m
Replace OWNER, REPO, and 123 with the actual repository owner, repository name, and pull request number.
The command creates a subscription if one does not already exist for the same resource and event types. It then opens the event stream and waits for an event.
By default, the command exits after receiving the first event. The timeout prevents the process from waiting indefinitely.
This is useful for scripts that need to pause until a particular development activity happens.
GitHub currently supports several pull request event types:
Event type | When it occurs |
|---|
com.github.pull_request.review.submitted.v1 | A review is submitted |
com.github.pull_request.state.changed.v1 | A pull request is merged, closed, reopened, or changes draft status |
com.github.pull_request.head.changed.v1 | The pull request's head branch changes |
com.github.pull_request.merge_conflict.v1 | GitHub detects a merge conflict |
com.github.pull_request.check_suite.status.changed.v1 | A check suite on the pull request's head commit completes |
You can listen for multiple event types by repeating the --event option or separating the event names with commas.
For example:
gh event listen \
--resource https://github.com/OWNER/REPO/pull/123 \
--event com.github.pull_request.review.submitted.v1 \
--event com.github.pull_request.head.changed.v1 \
--timeout 30m
This allows an automation process to respond to either a submitted review or a new commit.
Extracting Useful Information From Events
The event stream prints each event as a single-line JSON CloudEvent object.
For example, an event contains an identifier, an event type, and a data object. The data object includes an API URL that identifies the resource that changed.
You do not always need to process the complete JSON response. GitHub CLI supports --jq and --template, which allow you to extract the fields required by your script.
For example, to print the API URL associated with an event:
gh event listen \
--resource https://github.com/OWNER/REPO/pull/123 \
--event com.github.pull_request.review.submitted.v1 \
--timeout 30m \
--jq '.data.api_url'
You can also wait for a completed check suite and extract its conclusion:
gh event listen \
--resource https://github.com/OWNER/REPO/pull/123 \
--event com.github.pull_request.check_suite.status.changed.v1 \
--timeout 30m \
--jq '.data.conclusion'
A check suite conclusion can indicate success, failure, cancellation, a timeout, or another completion state.
This is useful when a downstream process needs to know whether a particular check suite completed successfully before continuing.
However, a pull request can have multiple check suites because different integrations may report their own results. Receiving one successful check suite event does not mean that every required check has passed.
For a complete picture, retrieve the latest check information after receiving the event.
Using Event Streams in a Build Automation Workflow
Consider a scenario where a team runs an automated validation process after a developer pushes changes to a pull request.
The team wants a separate process to wait for the CI check suites to finish and then decide whether another action is required.
A simple shell script can listen for check suite events and inspect their conclusions.
#!/usr/bin/env bash
set -euo pipefail
PR_URL="https://github.com/OWNER/REPO/pull/123"
echo "Waiting for a completed check suite..."
CONCLUSION=$(
gh event listen \
--resource "$PR_URL" \
--event com.github.pull_request.check_suite.status.changed.v1 \
--timeout 30m \
--jq '.data.conclusion'
)
echo "Received check suite conclusion: $CONCLUSION"
case "$CONCLUSION" in
success)
echo "The check suite completed successfully."
;;
failure)
echo "The check suite failed. Investigate the build."
exit 1
;;
cancelled|timed_out)
echo "The check suite did not complete successfully."
exit 1
;;
*)
echo "The check suite completed with another conclusion."
;;
esac
This example demonstrates how an external build process can wait for an event instead of continuously checking GitHub.
There is an important distinction: GitHub Event Streams do not directly start or replace GitHub Actions workflows. They provide an event subscription mechanism for an application or script. That client can then decide whether to invoke another workflow, call an API, send a notification, or continue its own execution.
For example, an external automation process could use gh workflow run after validating the relevant pull request state:
gh workflow run downstream-validation.yml \
--ref main \
-f pull_request_number=123
The downstream workflow would need to accept the supplied input and retrieve the appropriate pull request information.
In a real implementation, avoid triggering downstream work based only on the first event received. Retrieve the latest pull request and check information, verify the commit being validated, and confirm that the intended conditions are still satisfied.
This is particularly important when multiple commits or check suites are involved.
Managing Event Subscriptions
Event subscriptions have a lifecycle. They are not permanent registrations that can be created once and forgotten.
GitHub CLI provides commands to manage subscriptions:
gh event subscription create
gh event subscription list
gh event subscription view
gh event subscription delete
For example, you can create a subscription for a pull request:
gh event subscription create \
--resource https://github.com/OWNER/REPO/pull/123 \
--event com.github.pull_request.review.submitted.v1
The command returns a subscription identifier that can be used to manage or listen to that subscription.
To view active subscriptions:
gh event subscription list
To remove a subscription:
gh event subscription delete SUBSCRIPTION_ID
A subscription expires 24 hours after it is created. Each user, app, or installation token can have up to 100 active subscriptions.
When building automation that monitors several pull requests, maintain a clear subscription lifecycle. Remove subscriptions that are no longer needed and create new ones when existing subscriptions expire.
The gh event listen command can also reuse an existing subscription or create one automatically when supplied with a resource URL and event types.
Handling Disconnects, Duplicate Events, and Missed Updates
Event-driven automation needs to account for situations where events are repeated, delayed, or missed.
A common mistake is assuming that every event arrives exactly once and in the correct order. GitHub Event Streams does not provide that guarantee.
Events can be missed
Events are delivered only while the stream is open. Events that happen before the connection is established or while the client is disconnected are not replayed.
There can also be a short gap immediately after creating a subscription.
A safer approach is to establish the stream and then retrieve the current pull request state. This helps the client identify changes that may have occurred around subscription creation.
Events can arrive more than once
Your application should not assume that receiving an event means the corresponding operation has never been processed.
For operations that trigger builds, deployments, or notifications, use an idempotency strategy. For example, track the check suite ID or review ID and avoid processing the same resource repeatedly.
Events can arrive out of order
Two events associated with the same pull request may not arrive in the order in which the underlying changes occurred.
Instead of reconstructing the entire pull request history from event order, retrieve the latest state from the API URL included in the event.
Connections can end
If a stream ends unexpectedly, the client should reconnect using an appropriate retry strategy. GitHub sends heartbeat comments while the stream is idle, so clients should not interpret every quiet period as a disconnected connection.
GitHub CLI handles stream reconnection, but an automation process should still account for events that occur during a disconnection.
When the server indicates that a stream should reconnect, follow the documented outcome and refresh an expired token when necessary.
Security Considerations
Event Streams do not remove the need for proper authentication and permission management.
The token used by the client must have access to the pull request. For an integration that monitors multiple repositories, prefer GitHub App installation access tokens with the minimum permissions required.
Avoid placing personal access tokens directly in scripts or source control. Use a secure credential store or the environment's approved secret-management mechanism.
Also remember that an event is a signal to inspect a resource, not authorization to perform a sensitive operation.
For example, a review-submitted event does not automatically mean that the review was approved. The client must retrieve the review and inspect its state before triggering an approval-dependent action.
Similarly, a successful check suite event does not guarantee that all required checks for the pull request have completed.
Build and deployment automation should always verify the latest state before proceeding.
When to Use Event Streams Instead of Polling
Event Streams are useful when an application needs to wait for changes on a specific pull request.
They are particularly suitable for:
AI coding agents waiting for developer reviews.
Build automation waiting for check suite completion.
Development tools reacting to new commits.
Pull request management tools responding to state changes.
Scripts that need to wait for a merge or review without repeatedly calling the API.
However, Event Streams are not a replacement for every GitHub automation mechanism.
GitHub Actions workflow triggers remain the appropriate choice when a workflow should start in response to standard repository events such as a push or pull request activity.
Webhooks remain useful when GitHub needs to notify an external service through an HTTP endpoint. Event Streams are more appropriate when a client wants to maintain a connection and wait for changes without exposing a public endpoint.
The choice depends on where the automation runs, which events it needs, and how it handles missed updates.
Summary
GitHub Event Streams provide a practical way to react to pull request changes without continuously polling the GitHub API. By creating a subscription and opening a Server-Sent Events connection, applications and automation tools can wait for reviews, new commits, check suite completions, and other pull request events.
GitHub CLI makes this functionality easier to use through commands such as gh event listen and gh event subscription create. These commands are particularly useful for scripts and AI agents that need to wait for a specific development event before continuing.
The important part is to build reliable event handling around the stream. Events can be missed, duplicated, or received out of order, so automation should retrieve the latest resource state and avoid assuming that an event alone contains all the information needed to make a decision.
For teams building responsive development tools and CI/CD integrations, Event Streams offer another useful way to coordinate work around the pull request lifecycle.
Join the conversation! Your thoughts help the community grow.