Note
GitHub Event Streams is in public preview and subject to change. We may make breaking changes to the API, event types, and limits with short notice during the preview.
About GitHub Event Streams
GitHub Event Streams lets agents and integrations subscribe to changes on a resource instead of polling for them. It currently supports events for pull requests.
You create a subscription for a pull request once, keep a stream open on it, and GitHub sends you an event when something you've subscribed to changes. Your client can then fetch the latest state from the REST API.
Events are delivered over Server-Sent Events (SSE), so your client doesn't need a public endpoint the way webhooks do. This makes Event Streams a good fit for agents and tools running on a developer's machine.
Event Streams is only available on GitHub.com. It isn't available on GHE.com yet.
Before you start
-
Access: we are rolling out this feature on a wait list basis. To join the wait list, fill out the wait list form, and we will contact you when your account has been granted access. We enable Event Streams per account:
- For user tokens, we enable your user account.
- For GitHub App installation tokens, we enable the user, organization, or enterprise the app is installed on. This covers every app installed there, including the
GITHUB_TOKENin GitHub Actions, but not members' own user tokens.
Requests from other accounts return
403 Forbiddenwith the message "Event subscriptions are not enabled for this account". -
Token: use a user token (a personal access token, an OAuth token, or a GitHub App user access token) or a GitHub App installation access token. Apps authenticating as themselves aren't supported.
-
Permissions: the user or installation needs read access to the pull request you subscribe to.
Quickstart
These examples use the GitHub CLI (gh) for the API calls and curl for the stream.
1. Create a subscription
Replace OWNER, REPO, and NUMBER with the pull request's owner, repository name, and number.
EVENTS_URL=$(gh api -X POST /event-subscriptions \
-f resource_url=https://github.com/OWNER/REPO/pull/NUMBER \
-f 'event_types[]=com.github.pull_request.review.submitted.v1' \
-f 'event_types[]=com.github.pull_request.state.changed.v1' \
--jq .events_url)
The response includes the subscription's id, expires_at, and events_url. The --jq .events_url option prints only events_url, which you need in the next step. A new subscription returns 201 Created. If you already have a subscription with the same pull request and event types, you get that subscription back with 200 OK.
2. Open the event stream
Open the stream at events_url. gh api waits for the whole response before printing anything, so use a streaming client such as curl -N:
curl -sS -N -H 'Accept: text/event-stream' \
-H @<(printf 'Authorization: Bearer %s' "$(gh auth token --hostname github.com)") \
"$EVENTS_URL"
Open the stream before you trigger the activity you want to see. The stream only delivers events that happen while it's open.
3. Fetch the latest state
Each event indicates that a change occurred and provides an api_url. Fetch api_url with your token to read the current state of the review or pull request.
4. Delete the subscription
When you've finished, close the stream. Deleting a subscription doesn't close its open streams, so close the stream yourself first. List your active subscriptions with gh api /event-subscriptions to find the subscription's id. Then delete the subscription, replacing ID with that value:
gh api -X DELETE /event-subscriptions/ID
API reference
All routes are on https://api.github.com.
| Method | Route | Description |
|---|---|---|
POST | / | Create a subscription. |
GET | / | List your active subscriptions, newest first. |
GET | / | Get a subscription. |
DELETE | / | Delete a subscription. |
GET | / | Stream the subscription's events over SSE. |
Creating a subscription
The request body has two fields:
resource_url: the pull request's web URL, in the formhttps://github.com/OWNER/REPO/pull/NUMBER, or its REST API URL, in the formhttps://api.github.com/repos/OWNER/REPO/pulls/NUMBER, with no extra path, query, or fragment. Both forms name the same subscription, and the response always returns the web URL. URLs for a part of a pull request, such as a review, aren't accepted.event_types: one or more of the event types. Unknown event types return422 Unprocessable Content, and the error message names them.
Subscription responses include id, resource_url, event_types, created_at, expires_at, url, and events_url.
Limits
- A subscription covers one pull request.
- Subscriptions expire 24 hours after they're created. To keep receiving events, create a new subscription.
- Each user, app, and installation token can have up to 100 active subscriptions. Creating more returns
422with the message "Subscription limit exceeded". Delete subscriptions you no longer need.
Event types
| Event type | Sent when | api_url points to |
|---|---|---|
com.github.pull_request.check_ | A check suite on the pull request's head commit completes, whatever its conclusion. | The check suite |
com.github.pull_request.head.changed.v1 | The pull request's head commit changes, for example after a push. | The pull request |
com.github.pull_request.merge_ | GitHub finds that the pull request has a merge conflict. | The pull request |
com.github.pull_request.review.submitted.v1 | Someone submits a review that approves, requests changes, or comments. | The review |
com.github.pull_request.state.changed.v1 | The pull request is merged, closed, reopened, marked ready for review, or converted to a draft. | The pull request |
A pull request usually has several check suites, one per app, so one push can produce several check suite events, and a re-run produces another when it completes.
Each single review comment, and each reply to a review comment, also counts as a review.
Events currently tell you that something changed, not what changed. For example, a review event doesn't include the review's state, and a state change event doesn't say whether the pull request was merged or closed. Fetch api_url to find out.
Check suite events are the exception: their data.conclusion field is always present, so you can tell pass from fail without fetching. It's one of success, failure, neutral, cancelled, timed_out, action_required, stale, skipped, startup_failure, or unknown (a conclusion outside this list).
GitHub only checks for merge conflicts after someone views or requests the pull request, so merge conflict events can take longer to arrive than other events.
Event format
Each event in the stream has three fields:
id: the event's IDevent: the event typedata: the full event as a single-line JSON CloudEvent
Handling the stream
Event streams are long-lived connections, so your client needs to handle gaps, repeated or out-of-order events, and streams that end. Follow these practices to avoid missing or mishandling events.
-
Missed events: streams deliver events only while they're open, with no replay. You won't receive events that occur:
- Before you open the stream
- During a short window immediately after you create the subscription
- While you're disconnected
After you subscribe, fetch the pull request once to catch anything you missed.
-
Duplicates and ordering: you may receive the same event more than once, and events for one pull request can arrive out of order. Fetch the current state from
api_urlrather than relying on event order. For review and check suite events,api_urlidentifies the review or check suite, so you can use it to deduplicate. -
Heartbeats: while the stream is idle, the server sends a comment line starting with
:within 15 seconds of the last event or comment. Ignore these lines. -
Ending a stream: when the server ends a stream, its last event is
github.stream.end, with anoutcomeindata. Act onoutcome, not on the optionalreasonfield, because newreasonvalues may be added.subscription_ended: the subscription expired or you lost access to the pull request. Stop, and create a new subscription if you need one.reconnect: reopen the stream on the same subscription. Back off with jitter, and refresh your token first if it may have expired.
-
Unexpected disconnects: if a stream ends without a
github.stream.endevent, reconnect. -
Installation tokens: installation tokens expire after an hour, and streams opened with one end at the next access check after it expires. Create a fresh token before you reconnect. A
GITHUB_TOKENcan't be renewed, so delete the subscriptions it created before the job finishes.
Errors
Error responses include message, documentation_url, and status.
| Status | What to do |
|---|---|
400 | The request body isn't a JSON object. Fix the request. |
401 | Your token is invalid or has expired. Refresh it and retry once. |
403 | Event Streams isn't enabled for this account, or you're authenticating as an app rather than as a user or installation. Don't retry. |
404 | The subscription doesn't exist, has expired, or belongs to another user, or you can't access the pull request. Don't retry. |
422 | The resource_url or event_types is invalid, or you've reached the subscription limit. Fix the request, or delete subscriptions you no longer need. |
503 | Temporary. Retry after the number of seconds in the Retry-After header. |
500, 504 | Retry with backoff. |
Known limitations
- No "all checks completed" event: you get one event per check suite. To know whether all checks are done, fetch the pull request's check suites after each event.
- Pull request conversation comments: comments on the pull request's conversation tab don't produce events yet. Review comments do, as review events.
- Open streams after deletion: deleting a subscription doesn't close its open streams yet. Close the stream yourself before you delete the subscription.
- No replay: see Handling the stream.
Giving feedback
We'd love to hear what's working and what isn't. Share feedback in the GitHub Community discussion.