Listening for GitHub events
Resume work when a watched pull request or CI state changes.
Listening creates a subscription to a GitHub state change. The gateway polls GitHub; the model does not need to spend a turn repeatedly asking whether CI is done.
Use a listener when the event matters
Example:
Watch pull request 38 in Harbor Studio's dashboard repository. When its checks finish, inspect failures and prepare a fix. If they pass, report the result and wait before merging.
The agent uses create_subscription and related subscription tools. It supplies a name, instruction, repository owner/name, pull request number, events, and the destination conversation.
Supported watched events include:
check_suite.completed: CI has finished.pull_request.closed: the pull request was closed or merged.
A checkName filter can narrow the CI check of interest.
Polling and expiry
The default interval is 30 seconds, with a minimum of 15 seconds. Default duration is one hour. The agent can set a bounded duration, extend it, disable it, or delete it. Do not assume a listener watches forever.
Unchanged polls remain silent: they do not start model turns or send “still waiting” messages. A real watched change wakes the destination conversation with the saved instruction. The gateway must be running and able to reach GitHub.
Private repositories
Private repository polling uses the connected GitHub account/App authorization for that repository owner. Public repository polling can work without a connection. Access to one private repository does not authorize another.
No repository webhook is required for the normal polling flow. An optional webhook path is not a prerequisite for asking an agent to watch CI.
Interaction with objectives
Creating an enabled listener blocks an open session objective while it waits, preventing auto-continuation from generating repetitive status checks. A real wake reopens the objective so the agent can carry out the next step.
A listener event is a prompt to inspect the new state, not automatic permission to merge, publish, or deploy. The saved instruction and conversation protection still apply.