Using GitHub Event Streams - GitHub Docs
Skip to main content Skip to content Collapse sidebar Expand sidebar Using GitHub Event Streams GitHub Event Streams lets agents and integrations subscribe to changes on a resource instead of polling for them. In this article 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, so you can see each step of the API. If you use GitHub CLI 2.105.0 or later, the gh event commands handle subscribing, streaming, and reconnecting for you. See Using GitHub CLI commands . 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 Using GitHub CLI commands GitHub CLI 2.105.0 and later include gh event commands for Event Streams. These commands are also in public preview and subject to change. To wait for an event on a pull request, run gh event listen with the pull request's URL and one or more event types: gh event listen --resource https://github.com/OWNER/REPO/pull/NUMBER \ --event com.github.pull_request.review.submitted.v1,com.github.pull_request.state.changed.v1 gh event listen creates a subscription, or reuses your existing one for the same pull request and event types.
It then opens the stream and prints each event as one line of JSON. It reconnects when the stream drops, and creates the subscription again if it expires. By default, the command exits after the first event. This suits agents, which usually wait for a command to finish before they continue. --count N exits after N events, and --follow keeps listening until you stop it. --timeout stops waiting after a duration such as 30m , and exits with status 8 . --jq and --template format each event, as with gh api .
For example, --jq .data.conclusion prints only a check suite's conclusion. The command prints Listening for events. to stderr once the stream is open. Changes made before then aren't reported, so read the pull request's current state after you see this line. To manage subscriptions directly, use gh event subscription list , create , view , and delete . gh event listen doesn't delete its subscription when it exits. Subscriptions expire after 24 hours.
When gh detects that an agent is calling it, commands such as gh pr create , gh pr view , gh run view , gh run watch , and gh api suggest gh event listen instead of polling. For all options, run gh event listen --help . API reference All routes are on https://api.github.com . Method Route Description POST / event-subscriptions Create a subscription. GET / event-subscriptions List 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}/ events 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 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 type Sent when api_url points to com.github.pull_request.check_ suite.status.changed.v1 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_ conflict.v1 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
The rest of this page is on the live site.