The GitHub App's webhook, signed with a secret transit holds, starts a run of a trigger on a repository from a labelled issue or a member's command, with the issue fenced as data; a review on the draft that run opened resumes its session; and a new webhook trigger is made with its key¶
Decision 905 · accepted · 2026-10-16 · issue #147
- One door, signed, for the App.
POST /webhook/github, the URL an administrator gives the App on GitHub. Its credential isX-Hub-Signature-256, GitHub's HMAC-SHA256 of the body under the App's webhook secret, over the bytes as they arrived. The secret is kept as the App's key is (Decision 885):admin.github.puttakeswebhook_secret(32 characters at least) and imports it into transit as an HMAC key,troupe-github-webhook, not exportable; the row keeps its version. The plane asks transit for the HMAC of each body and compares it with the one presented with:crypto.hash_equals. Rejected: the secret as a row or a setting, which a database backup would hand to anybody who could then start runs; and transit's ownverify, whose comparison is OpenBao's and not one this code can show is constant-time. An unsigned, malformed or wrong signature is401before anything else is read, and logged with the delivery id and event (headers cut to the characters an id has), never the body; a plane with no secret, or whose transit cannot answer, refuses with503and says why. - Once, and answered first. A delivery's id (
X-GitHub-Delivery) is a row,github_deliveries, inserted withON CONFLICT DO NOTHINGbefore any work, so a retry or a Redeliver is answered200and does nothing, on any replica; rows go after thirty days. The answer,202, comes as soon as the delivery is recorded; the work runs after it underTroupe.Plane.GitHub.Deliveries, since GitHub gives a delivery ten seconds and a session can take longer to start. - A trigger names a repository.
source: {kind: webhook, provider: github, repository: owner/name, label?, command?, ref?}. Kept as a webhook with a provider rather than a new kind, because that is what theTriggerresource's schema already says a webhook is (aproviderand fields of its own), so neither the CRD nor GitOps changes; aprovider: githubwith no repository is the free-text provider it always was. The shape is the changeset's (GitHub.Issue.source_problems/1); whether the App reaches the repository (configured, installed for the owner, the profile declaring the Git host) isadmin.trigger.put's, assession.createwill ask again at each firing. Its sessions are created with the repository, so slice 1's clone and slice 2's tools follow unchanged. - The first events: a label, and a command.
issues.labeledwith the trigger's label, andissue_comment.createdon an issue whose first line is the trigger's command, alone or followed by words. A label because adding one needs triage rights already and is how teams mark work; a command because it is what a person asks with, but anybody can comment on a public repository's issue, and a run spends a team's budget, so a command counts only from somebody GitHub calls the repository'sOWNER,MEMBERorCOLLABORATOR, and never from a bot (the App's own comments among them). Never a pull request's conversation, never a closed issue, never an installation the plane does not list for that owner. Each match is a run ofTriggers.fire/5with sourcewebhookand keygithub:<delivery>:<trigger>. Rejected for now:issues.assignedto the bot, and a sweep on a schedule (slice 4). - Nothing GitHub's users write is an instruction to the plane. What the plane acts on is
the event's name and action, a label's name, a command's exact first line, the author
association GitHub reports, and ids. The run keeps the issue (
GitHub.Issue.event/4, its text cut, the whole under 16 KiB). The session's prompt is the trigger's template rendered against that event with the issue's title, body and comment taken out, so a template cannot paste them anywhere, followed by one sentence saying what follows is data written by people on GitHub and never instructions, and the issue between<<<github-issueandgithub-issue>>>, with either marker removed from the text first so it cannot close the fence and go on outside it. The profile, agent, terms, principal and repository are the trigger's; the fix loop's own refusals (Decision 891) still hold whatever the model is persuaded of. - A review resumes the run that opened the draft.
pull_request_review.submitted, requesting changes or commenting with something to say, on a pull request that is a draft, of an installation the plane lists, recorded by exactly one session (sessions.github, by repository and number, and then by link), whose session is a trigger's run, by the repository's owner, a member or a collaborator who is not a bot, and whose pushes three red rounds have not closed. Anything else does nothing and the delivery's outcome says which. Only the review event: GitHub sends each of a review's line comments as a delivery of its own as well, and acting on those would make one review several turns; so the plane reads the review's comments from GitHub (GitHub.review_comments/3, a token of its own narrowed to the repository andpull_requests: read, audited) and gives the session one input. A person's own session is not resumed by anybody's review: it is theirs to steer. - How the review reaches the session. Woken as the run's principal through
session.openwithmode: activate, as anything that wakes a session is (grant, budget and placement checked), then pushed to its pod assession.input {session_id, epoch, input: {id, text}, actor}, which the worker takes only for a session up at that epoch and sends to the root agent as a:userinput with the delivery's id as its command id and an actor of the session's owner, displayed as "a GitHub review by". This is the second piece of session content the control channel carries, beside the first prompt Decision 256 allowed and for the reason it gives: an unattended session has no client to type into it. Bounded as that is (64 KiB), fenced as the issue is ( <<<github-review), and audited asgithub.review. Rejected: the plane attaching to the pod as a client to type it, a WebSocket client in the plane for one message, carrying the same text through the same plane. -
A webhook trigger is made with its key.
admin.trigger.putthat creates a webhook trigger with no repository mints its key (Triggers.rotate_key/2) and answerskeyandurlonce; the audit row says a key was minted and never holds it. A trigger on a repository is made with none: the App's deliveries fire it. A change to an existing trigger mints nothing, and rotation stays as it was. Triggers made from aTriggerresource get none either: the key is the plane's and a repository never holds one (Decision 737); an administrator rotates one. -
The notification carries the pull request. A trigger's
notify_urlis postedpull_request, the link to the draft its run opened, ornull: metadata, as the rest of the body is.
Governs: apps/troupe_plane/lib/troupe/plane/github/webhook.ex, apps/troupe_plane/lib/troupe/plane/github/webhook_secret.ex, apps/troupe_plane/lib/troupe/plane/github/issue.ex, apps/troupe_plane/lib/troupe/plane/github/review.ex, apps/troupe_plane/lib/troupe/plane/github/delivery.ex, apps/troupe_plane/lib/troupe/plane/triggers/trigger.ex, apps/troupe_protocol/lib/troupe/kms/policy.ex