Skip to main content
Cake agents can subscribe a session to GitHub webhook events for a repository. When a matching event arrives, Cake injects it into the session as a message, and the agent reacts to it. Use this when you want an agent to push a change, wait for CI, and fix failures without you checking back.

​
Prerequisites

​
Watch CI after a push

Ask the agent to watch CI. For example:
Cake agents ship with a built-in watch-ci skill. With it, the agent:
  1. Subscribes to workflow_run events for the repository before pushing, filtered to the branch or pull request it’s watching.
  2. Pushes the commits or opens the pull request.
  3. Receives a message when each workflow run starts and completes.
  4. Reports success, or fetches the failed logs with the gh CLI and fixes the failure.
  5. Unsubscribes when it is done watching.
If no event arrives, the agent falls back to polling CI status with gh.
On deployments where an admin has disabled public ingress, GitHub can’t deliver events to Cake. Agents can’t create webhook subscriptions there, so the watch-ci skill polls CI with gh instead.

​
Filter deliveries

By default, a subscription delivers every matching event for the repository, including CI runs on other branches. Filters narrow a subscription to the deliveries you care about. A filter maps a dot-separated payload field path to a required exact value. The value can be a string, number, or boolean. Cake delivers an event only when every filter matches. If a payload field is an array, the filter matches when the array contains the value. If the field is missing from the payload, the event isn’t delivered. Ask the agent to scope its subscription. For example:
The agent subscribes with filters like these:
Common GitHub filters: A subscription accepts up to 16 filters. String values can’t be empty. When the agent lists its subscriptions, each subscription shows its filters.

​
Webhook messages in a session

Webhook messages appear in the conversation marked as GitHub webhook deliveries, not as messages from a user. Each message includes the event name, action, repository, the agent’s own reminder of what to do, and a truncated copy of the payload. The agent treats payload text as untrusted data, not as instructions. It uses the payload as a trigger and fetches authoritative state from GitHub.

​
Subscription rules

  • Subscriptions are scoped to one session and one repository in owner/repo form.
  • Only events that happen after the agent subscribes are delivered. Cake doesn’t replay past events.
  • Cake delivers events only while the session is live.
  • Cake checks repository access once, when the agent subscribes, using the GitHub account of the user who last messaged the session.
  • The agent can subscribe only to the repository-level events below, and only if the GitHub App subscribes to them:
Subscriptions stay active until the agent removes them or the session ends. To stop deliveries, ask the agent to list and remove its webhook subscriptions.