Skip to main content
Skip to content

Using GitHub Event Streams

GitHub Event Streams lets agents and integrations subscribe to changes on a resource instead of polling for them.

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_TOKEN in GitHub Actions, but not members' own user tokens.

    Requests from other accounts return 403 Forbidden with 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.

MethodRouteDescription
POST/event-subscriptionsCreate a subscription.
GET/event-subscriptionsList your active subscriptions, newest first.
GET/event-subscriptions/{subscription_id}Get a subscription.
DELETE/event-subscriptions/{subscription_id}Delete a subscription.
GET/event-subscriptions/{subscription_id}/eventsStream 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 form https://github.com/OWNER/REPO/pull/NUMBER, or its REST API URL, in the form https://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 return 422 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 422 with the message "Subscription limit exceeded". Delete subscriptions you no longer need.

Event types

Event typeSent whenapi_url points to
com.github.pull_request.check_suite.status.changed.v1A check suite on the pull request's head commit completes, whatever its conclusion.The check suite
com.github.pull_request.head.changed.v1The pull request's head commit changes, for example after a push.The pull request
com.github.pull_request.merge_conflict.v1GitHub finds that the pull request has a merge conflict.The pull request
com.github.pull_request.review.submitted.v1Someone submits a review that approves, requests changes, or comments.The review
com.github.pull_request.state.changed.v1The 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 ID
  • event: the event type
  • data: 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_url rather than relying on event order. For review and check suite events, api_url identifies 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 an outcome in data. Act on outcome, not on the optional reason field, because new reason values 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.end event, 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_TOKEN can't be renewed, so delete the subscriptions it created before the job finishes.

Errors

Error responses include message, documentation_url, and status.

StatusWhat to do
400The request body isn't a JSON object. Fix the request.
401Your token is invalid or has expired. Refresh it and retry once.
403Event Streams isn't enabled for this account, or you're authenticating as an app rather than as a user or installation. Don't retry.
404The subscription doesn't exist, has expired, or belongs to another user, or you can't access the pull request. Don't retry.
422The resource_url or event_types is invalid, or you've reached the subscription limit. Fix the request, or delete subscriptions you no longer need.
503Temporary. Retry after the number of seconds in the Retry-After header.
500, 504Retry 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.