Research: GitHub App with real Check Run buttons, as a future alternative to Markdown checkboxes

[ineedjet]

Summary

Research issue, not committed work. The proposal lifecycle's control surface (Propose/Apply/Reject/Distill/Rework) currently uses native GitHub Markdown checkboxes in a single comment — cheap, works in any repo with zero extra infrastructure, and sufficient for the current MVP. This issue tracks the known limits of that approach and what a GitHub App-based alternative would look like, for whenever (if ever) those limits become a real problem.

Current approach and its limits

Documented in the README (see "Known limits of Markdown checkboxes as the control surface"):

• No native "click" signal — checking a box and hand-editing the comment's raw text both fire the identical issue_comment: edited event. No way to distinguish a genuine UI interaction from a directly edited [x].
• No mutual exclusivity — nothing stops a human from checking more than one box (e.g. both Apply and Reject) in the same edit. Both jobs would run, sequentially (they share a comment_id-keyed concurrency group), in an unspecified order, rather than the input being rejected as ambiguous.
• No delta signal — any edit to the comment fires the same event; intent is always re-derived from the comment's current full body, never a diff of what changed.

None of these have caused a real problem yet. This issue exists so the option is on record, not to schedule the work.

The GitHub App alternative

GitHub's Checks API supports actions on a check run — real, clickable buttons (not text) rendered in the PR/commit UI. Each button click delivers a check_run webhook with action: requested_action and a requested_action.identifier field, unambiguously naming which button was pressed.

await github.rest.checks.create({
  owner, repo, head_sha,
  name: "proposal-review",
  status: "completed",
  conclusion: "action_required",
  output: { title: "Proposal ready for review", summary: "Choose an action below" },
  actions: [
    { label: "Apply", description: "Apply this proposal", identifier: "apply" },
    { label: "Reject", description: "Reject this proposal", identifier: "reject" },
  ],
});

This would remove all three limits above by construction: a button click is a discrete, unambiguous event (not a text diff to parse), and the UI can enforce exclusivity if desired (e.g. removing/disabling other buttons once one is clicked).

The real cost: this needs an actual GitHub App with its own webhook-receiving server, not just more reusable GitHub Actions workflows. check_run.requested_action isn't cleanly consumable from a plain on: check_run Actions trigger the way issue_comment is today — community discussions confirm there's no simple native path from "button clicked" to "GitHub Actions workflow runs" without a real app in between. That's a materially different (and heavier) piece of infrastructure than anything StarCast has built so far.

Open questions (not answered here)

• Does StarCast host this App itself, or does each consumer register their own? (Affects who holds the App's private key/webhook secret.)
• Where does the webhook receiver run — a small persistent service, or can it be a serverless function invoked per-webhook?
• Does this replace the control comment entirely, or complement it (e.g. buttons for the common path, comment checkboxes as a fallback)?
• How does this interact with Explore a persistent multi-channel agent runtime #7's exploration of a persistent multi-channel agent runtime — a webhook receiver is exactly the kind of "gateway" that issue already describes.

Non-goal

Not a proposal to build this now. The Markdown-checkbox approach is sufficient for the current MVP; revisit only if the documented limits become a real, repeated problem in practice.

Related

• Extract reusable proposal and review primitives #11 documents these limits as an accepted-for-now design tradeoff; this issue is the deferred "what would fix it" research.
• Explore a persistent multi-channel agent runtime #7 (persistent multi-channel agent runtime) already explores gateway/webhook infrastructure that a GitHub App receiver would naturally live alongside.