§ Writing6 min read

Treat GitHub event streams as wake-ups, not a queue

GitHub's preview wakes a pull-request agent without polling, but disconnect gaps and 24-hour subscriptions make state reconciliation part of the design.

GitHub CLI 2.105.0, released on 18 November, adds gh event listen for pull-request changes. It can wait for a review or completed check suite instead of polling, and prints each event as CloudEvent JSON with a data.api_url for the changed object (release notes).

An agent needs a trigger, then a reconciliation step. GitHub’s CLI manual puts the gap plainly: “Events that happen while it is disconnected are not delivered.” The listener reconnects, but it cannot tell the agent what it missed. I would treat each event as a wake-up signal and reread the current pull request before deciding what work remains.

This is design analysis with illustrative TypeScript. I have not run the preview or measured wake-up latency, token use or rate-limit savings. The running example is a hypothetical review assistant watching one pull request at a time.

What the stream gives you

The 17 November preview announcement describes a client subscribing to a pull request and keeping a connection open for changes. It says all GitHub plans are eligible after waitlist approval. No public webhook endpoint is required, so a local tool can receive events while running on a developer’s laptop. The CLI manual limits Event Streams to pull requests on github.com, not GitHub Enterprise Server or GHE.com.

The supported event types cover submitted reviews, changes to pull-request state or head, merge conflicts and completed check suites. The CLI can exit after the first event, wait for a count, or follow the stream until stopped. Its output is one CloudEvent JSON object per line; data.api_url points to the review, pull request or check suite that changed (gh event listen manual). Fetch that object, then separately read the current pull-request head and checks before dispatching agent work.

For a listener that stays open, --follow is explicit. The default exits after the first event (manual):

gh event listen --resource https://github.com/OWNER/REPO/pull/123 --event com.github.pull_request.review.submitted.v1 --follow

GitHub says the preview can reduce polling, wasted tokens and rate-limit requests, but its announcement includes no comparative measurements. I have not tested the service.

The listener prints a status message when it attaches. The manual says earlier events are not replayed and recommends reading the current pull request after that message, even if the client read it before starting the listener. On reconnect, do the same. The event stream does not identify every change the consumer missed.

The command manages subscriptions as well as reading them. A subscription expires after 24 hours, and each account has a limited number at a time (gh event listen manual). Renewal and attachment status belong in the service’s health checks.

Where state can drift

Moment Documented behaviour What I would do
First attach Earlier events are not replayed Read the current pull request after the stream attaches
Live change Event points to a changed object Fetch it, then read current pull-request state
Check suite One event per completed suite Query the pull request’s full check state
Disconnect Listener reconnects, gap events are missed Reconcile again before scheduling agent work
Subscription age Expires after 24 hours Renew deliberately and monitor attachment

A check-suite event is especially easy to misread. A pull request can have several suites, and the manual says each sends its own event when it completes. One success event does not mean every required check has passed. GitHub’s suggested pattern is to read the pull request’s checks after each event, for example with gh pr checks (manual).

The stream tells the consumer that something changed; it does not keep the application’s pending work, retry state or completion record. I would put those in a queue the application owns, then use reconciliation to repair any gap.

The running example: one review assistant

Suppose a review assistant watches a pull request and drafts a bounded review note. It should not treat each JSON line as a command to run the model against whatever happened to be in the event. The event can be old by the time a worker receives it. A new commit may already have replaced the head, or other checks may still be running.

I would keep the listener small. It checks that the event belongs to the configured pull request, fetches the changed object through data.api_url, then asks GitHub for the current pull-request head and all relevant check state. It upserts a task in the application’s own durable queue, using the current head and changed object to make retries and repeated wake-ups safe. The task contains enough provenance to explain why it exists, but the agent reads the current patch and review context when it starts.

The sketch below does only that: fetch the event target, read current pull-request state and upsert a queue item. The adapters stand in for GitHub API calls and the application’s queue; the code is illustrative and has not been run.

type Wakeup = {
  type: string;
  resourceUrl: string;
  data: { api_url: string };
};

type PullRequest = { id: number; headSha: string };
type ChangedObject = { id: string | number };
type Check = { id: number; status: string; conclusion?: string };

type GitHub = {
  changedObject(url: string): Promise<ChangedObject>;
  pullRequest(url: string): Promise<PullRequest>;
  checks(headSha: string): Promise<Check[]>;
};

type Queue = {
  upsert(input: {
    key: string;
    headSha: string;
    checks: Check[];
  }): Promise<{ id: string; created: boolean }>;
  enqueue(id: string): Promise<void>;
};

async function reconcile(event: Wakeup, github: GitHub, queue: Queue) {
  const [changed, pullRequest] = await Promise.all([
    github.changedObject(event.data.api_url),
    github.pullRequest(event.resourceUrl),
  ]);
  const checks = await github.checks(pullRequest.headSha);
  const task = await queue.upsert({
    key: [pullRequest.id, pullRequest.headSha, event.type, changed.id].join(":"),
    headSha: pullRequest.headSha,
    checks,
  });
  if (task.created) await queue.enqueue(task.id);
}

GitHub does not supply a queue identifier, so the key is my own design choice. In a real consumer I would make it include the event’s stable identity and the current pull-request revision. A newer head becomes new work. A repeated wake-up for the same changed review or check can find the existing task instead of starting duplicate analysis. The task store also needs a state for superseded work: if the branch moves while the agent is running, the result for the old head should not be presented as a review of the new one.

The assistant itself can stay read-only. It can inspect the current diff and checks and prepare a comment for a person to review. If the workflow later gains permission to write a review or merge, that is a separate authority decision in the tool executor. Receiving an event is evidence that a resource changed; it is not approval to change that resource.

Reconcile on attach and reconnect

I would make reconciliation run at three points: after the first attachment, after every reconnect, and after a relevant event arrives. The first two close the gaps where no event exists. The third prevents the agent from treating the event payload as authoritative state. When several changes arrive close together, I would coalesce the reads: reconcile the latest pull-request head and checks, then schedule work for that state.

For operations, I would expose the last attachment time, subscription expiry, last reconciled pull-request head and task state: queued, running, superseded or complete. A connected stream with failing reconciliation is still behind. A periodic reconciliation can repair state while the connection is down, although it brings back some polling by design.

The CLI manual describes reconnect and missed events, but says nothing about ordering or exactly-once delivery. I would not build on either assumption. Make reconciliation idempotent and use current GitHub state as the source of record.

What I’d do on Monday

  1. Start a subscription, wait for the attach message, then read the pull request’s current head and checks.
  2. Put wake-ups into an application-owned durable queue; do not treat the stream itself as queued work.
  3. Reconcile after every reconnect and before the agent acts on a review or check event.
  4. On check-suite events, query all pull-request checks rather than infer completion from one suite.
  5. Track attachment, renewal, last reconciled head and task state; test the 24-hour expiry and a dropped connection.
  6. Keep review generation read-only until a separate policy check authorises any write.
  7. Measure wake latency, API requests and model input on your own workload before claiming a saving over polling.

Limitations

The preview is behind a waitlist and limited to github.com. GitHub’s announcement and CLI manuals do not specify a replay window, event ordering, delivery guarantee or delivery SLO. The manual does say the listener reconnects while missing events from the gap. I would keep reconciliation and a fallback trigger until those constraints fit the workload.

Sources


  1. 7 min read

    A performance agent needs a stop condition

    OpenAI's Performance Factory describes an agentic regression loop. The harder engineering problem is deciding what evidence lets a production task close.


  2. 7 min read

    An agent monitor starts with a data policy

    Google's anomaly detector reads agent content after a run. Decide what enters telemetry, who can read it and what happens when the monitor flags a session.


  3. 7 min read

    A2UI's catalog is an API contract

    A2UI 1.0 lets agents compose native screens from registered components. Treat the catalog as a versioned client API, and keep data exposure and action authority explicit.