GitHub Is the Bus for AI Agents
Our agents used to push and stop while a human relayed CI failures and review comments. Here is the ai agent pull request workflow we built, with GitHub as the bus and completion loops.
Founder / CEO
Bottom Line
- Agents that post and forget turn a human into the message bus, noticing red CI, new comments, and finished fixes, then re-waking the right agent.
- We made GitHub the bus and gave authors and reviewers explicit completion loops, so each agent stays on the pull request until its own job is verified on the current head.
- The author hands off with one formal re-request per reviewer per round, only after feedback is addressed and CI is green; the reviewer wakes on that re-request, not on every push.
- Quiet signals keep the bus cheap: an eyes reaction before work starts, a thumbs-up instead of an echo, and silence while CI is red.
- The default mode is prepare, where a human approves a packet. Auto is opt-in, and no author, reviewer or supervisor agent merges, marks ready, or force-pushes.
The first version of our agent workflow ended at the push. An author agent opened a pull request, CI ran, a reviewer agent left comments, and then everyone stopped. When CI went red or a comment landed, a human had to notice, copy the context, and wake someone. The human was the message bus between two pieces of software that could both read GitHub.
This post describes the ai agent pull request workflow we built to remove that courier job. GitHub is the bus, and each agent role has a completion loop that defines when it is done. It is one part of a larger system described in how to build an AI software factory safely. Humans still approve outcomes, but approve work instead of relaying messages.
Agents that post and forget
The author stopped after the push, because pushing felt like the end of the task. The reviewer stopped after the first review. Neither definition of done included the other.
So the real workflow was this: CI fails, a human sees an email and pastes the failure into the author chat. A reviewer comments, a human tells the author. The author fixes it, and a human tells the reviewer to look again. Every hop cost attention, and with several reviewers we needed several humans nudging.
The fix was a shared state machine where the work already lives, not a smarter agent: the pull request, its checks, review threads, reactions, and reviewer requests. Agents read what they need there and write their signals there.
What changed, before and after
| Before | After |
|---|---|
| A human relays red CI, new comments, and "please re-check" between agents | Agents watch the same pull request and wake on GitHub events |
| Author is done at the first push | Author is done only when CI is green, the description matches the head, and review activity is handled |
| Reviewer is done when comments are posted | Reviewer is done when its own findings are verified on a green head, or re-flagged |
| Informal "check again" after the author replies | Author formally re-requests the reviewer, and the reviewer wakes on that request |
| Every wake spends an agent turn | A gate skips duplicate and noise wakes before spending tokens |
| N reviewers means N humans to nudge | Each reviewer watches its own threads and the author sees the union on the bus |
The wake gate in the last two rows gets its own post: zero-token wakes for AI agents.
The author completion loop
An authoring agent is done only when all five of these hold on the current head, not when it pushes or when a first CI run looks green:
- Implementation and verification. Local quality gates pass and self-review has zero blocking findings.
- The pull request artifact is current. The title, summary, and test plan match the branch, and a hidden marker in the description names the current head.
- Required CI is green. The complete required-check view for the head, including a green CI Gate. Failures are root-caused, not dismissed as flaky.
- Review activity is handled. Each thread needing author action is fixed, dismissed with a reason, or escalated to a human.
- The reviewer is formally re-requested. Once a reviewer's feedback is addressed and CI is green, the author re-requests that reviewer's review on GitHub.
The fifth item is the handoff: at most one re-request per reviewer per round of addressed feedback, not one per thread. Identities GitHub cannot request, such as certain bots, are noted in the packet and watched informally. A re-request is not a thread resolve or a ready mark.
Stay on the pull request after push
After the first push, the author agent arms a watcher and stays on the pull request. On each wake it triages CI and reviews, refreshes the title and description if the head or scope changed, and re-arms. It stops when the five conditions hold or a human says stop.
Authors never resolve threads
This is the rule people find strangest. An author agent never resolves a review thread, by any channel: not the watcher's resolve option, not the GraphQL API, not a forge tool, not the web UI. It replies and leaves the thread open, ending with "leaving open for reviewer verification". The person who raised a concern should confirm it was fixed, or a green-looking pull request can hide unverified feedback.
The reviewer completion loop
A reviewing agent is done when its own findings are verified on the current head or explicitly escalated, not when it submits a review.
After posting findings, the reviewer arms its own watcher on reviews and CI. It wakes on two events: the author's formal re-request, and a new head that arrives with required CI green. It does not wake on every push. The second wake exists because a shared login cannot use a re-request at all, and a green head with no open threads still deserves a look.
Silence while CI is red
If required CI is pending or failing when the reviewer wakes, it defers silently. It does not pull job logs, root-cause the failure, or post a diagnosis. The author owns CI and is usually already pushing a fix, so a reviewer comment on a red build is noise. The one exception is a build that stays red across several consecutive pushes with no author fix attempt, which suggests the author loop is stuck. That earns one short flag, not repeated diagnosis. One opt-in carve-out, the verify-on-reply watch, appears in the supervisor section below; every other thread keeps the CI-green rule.
Because CI is request-only on our pull request branches, there is a state between pending and failing: no run exists on the head. That is "not requested", not green and not a failure; the author requests it and the reviewer keeps waiting. Why CI works this way is covered in request-only CI for AI agents.
Verify, then resolve or re-flag
With CI green, the reviewer re-fetches the diff and the specific lines or behavior its comment named, checking that the fix matches the finding, not merely that a new commit exists. If satisfied, it replies briefly with a hidden marker recording the head commit it verified. In auto mode the reviewer-role watch then resolves its own thread; in prepare mode it drafts the reply and a resolve recommendation. If the fix is partial or wrong, it says what is missing. A thread resolved by someone else without the marker is still treated as needing verification.
A queue-level supervisor above the loops
The loops above are per pull request. A supervisor decides which pull requests in the queue need a loop started. A shell poller reads every open pull request. Pure rules, a tested JavaScript module, choose exactly one next step per pull request: start a review, recheck a pushed head, ask the author to fix CI or resolve conflicts, or wait. A local ledger records only what this checkout launched and delivered; GitHub stays the source of truth for outcomes.
The supervisor wakes the executor once per decision key. Quiet steps, such as waiting on CI, an approval, the author, or a review already running, wake nothing, and a key is marked once handled so it never fires twice. In prepare mode every wake is a recommendation the human approves first. In auto mode the executor hands a fixed brief, verbatim, to a background worker, because added words such as "triage by risk" made workers skip evidence their review skill requires.
The worker stages exactly one unsubmitted draft review at the current head: inline feedback for the author, or an approval-intent body with evidence when the change is clean. The human inspects and submits it. The supervisor never approves, requests changes, merges, marks ready, requests reviewers, or resolves threads for a person.
Its follow-up differs from the reviewer loop. When the human's review is waiting on the author, the supervisor arms a reviewer watch in verify-on-reply mode. It wakes when the author pushes and replies, even before CI is green, reruns the finding's recorded reproduction on the new head, then launches a fresh review that stages a new draft. That path replies to nothing and resolves nothing, in either mode, because GitHub would attribute it to the human. The human resolves after reading the draft.
Authors merge their own pull requests once approvals are met. Someone else's ready pull request waits quietly, unless an opt-in flag posts one fixed, pre-approved line per head saying approvals are met and CI is green.
Quiet signals on the bus
A busy bus gets noisy, so a few conventions keep the pull request readable for humans.
- Eyes reaction first. Before it loads a diff, edits, pushes, or replies, an agent reacts with the eyes emoji. The author reacts once on the top-level review, not on every inline thread. The reviewer reacts to the author's leave-open reply it is about to verify. Never a presence comment like "looking at this".
- Confirm-only means a thumbs-up. When one agent only agrees with another and has no new facts, it adds a thumbs-up or stays silent, with no echo comment.
- Net-new signal only. Reviews and replies carry a finding, evidence, and a fix; machine facts live in markers.
If a token cannot react, the agent skips the acknowledgment rather than falling back to a comment. Reactions leave no text to misread as work.
Writing to GitHub from different hosts
A failed write is not proof that posting is impossible, since some hosts can read and push but not comment. We wrote down an ordered list of channels: first the command line, when the session token can write; then the host's own pull request tools; then a prepare packet with the exact text drafted for a human to paste. A permission error means try the next channel.
Prepare by default, auto on request
All of these loops run in one of two modes. The default is prepare: on each wake the agent builds a packet with proposed fixes, draft replies, planned re-requests, and a short ready-for-approval summary, then stops. Nothing is committed, pushed, posted, re-requested, or resolved until a human approves.
Auto mode exists only on explicit request. The agent then executes the clear actions on wake: fix CI and push, request CI again for the batch, post replies, re-request reviewers, and, for a reviewer-role watch, resolve its own verified threads. In either mode, no agent merges, marks a draft ready, approves as a human reviewer, or force-pushes. Ambiguous or security-relevant items escalate. The caps that stop agents volleying forever are covered in stopping AI agents from arguing forever.
Honest limits
- Automatic wake is host-dependent. Some agent hosts support a wake transport and some have none; where there is none, a human prompt re-enters the loop. We document that rather than pretend.
- Same-login author and reviewer is unsupported. Sessions posting as the same login cannot re-request each other, and human and agent traffic blur together. The reviewer needs its own write identity, or the work runs in a single-session loop.
- This is a pilot. We are rolling it out gradually, and these rules are not a finished system.
- Agent verdicts do not replace human approvals. Required team approvals still gate merges; a reviewer agent's resolve does not satisfy them.
Lessons
- Define done per role. Posting a review or pushing a branch is an action, not an outcome; write the conditions that must hold on the current head.
- Use the system of record as the bus. Do not invent a side channel.
- Hand off with one explicit event. A formal re-request is clearer than inferring intent from pushes.
- Separate who fixes from who verifies. Authors leave threads open; reviewers resolve their own with a head-tied marker.
- Prefer reactions and silence to prose. Presence, agreement, and someone else's red CI need no comment.
- Default to a human-approved packet. Unattended execution is a per-pull-request opt-in.
The handoff only works if each side can be woken cheaply and told apart from noise, which is mostly a filtering problem.
