Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/cursor-review/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -287,6 +287,7 @@ All optional except `workflows_ref` (required, no default) — pass them under
| `run_without_label` | `false` | Run on plain PR events instead of requiring the trigger label. Also requires widening the caller's `types:` — see [the setup guide](../../docs/callers/cursor-review.md). |
| `blocking` | `false` | Adds the fail-closed **Blocking gate** check: red while any cursor-review finding thread is unresolved and non-outdated, and red when the round that should have produced those threads did not land (including an over-cap skip). Blocking the merge additionally requires marking that check required in the caller's ruleset — see [the blocking section above](#optional-make-the-review-blocking). |
| `approve_max_severity` | `''` (off) | Opt-in auto-approve: `medium`, `low` or `nit` → the bot approves (pinned to the reviewed commit) when every finding is at or below it and requests changes when any is above; anything else fails the run. Read the trust model in [the setup guide](../../docs/callers/cursor-review.md#auto-approve) first — the approval is no stronger than push access. |
| `defer_approval` | `false` | For a caller that runs cursor-approve after this workflow: an APPROVE outcome still reports `approve_gate` = `pass` but posts no approval and resolves no thread, and withdraws the approver's own earlier auto-approvals and requests for changes, so cursor-approve's decide is the only approver. |
| `max_rounds` | `5` | Per-PR review-round cap; `0` → none. Counts the posting identity's consolidated reviews since `needs-human-review` was last removed; at or over the cap the panel is skipped, the PR is labelled `needs-human-review`, one comment lists the latest round's open findings above the threshold, and the `approve_gate` output is `capped`. Fails open on a read error. See [the setup guide](../../docs/callers/cursor-review.md#round-cap-and-the-approve_gate-output). |
| `runs_on` | `'"ubuntu-latest"'` | JSON-encoded `runs-on` (same shape as `cursor-review-auto-label.yml`'s) for the four credential-free heavy jobs only: `diff-size`, `preflight`, the `review` panel and `consolidate`. The gate, ledger, Slack notices and every job holding the App token or `pull-requests: write` stay on GitHub-hosted `ubuntu-latest`. Those four run models with unsandboxed shell over PR code, so use a self-hosted pool only if each job gets a fresh pod (fresh filesystem and `$HOME`), holds no cloud identity or token, and can't reach private networks or the metadata server. The image must be linux/x64 with bash, git, curl, jq, python3, gh, tar and GNU coreutils. |

Expand Down
94 changes: 90 additions & 4 deletions .github/cursor-review/auto-approve.py
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,18 @@
reviewer's most recent review, so a round-1 APPROVED would otherwise keep
counting through a degraded re-run at the same head.

``--defer-approval true`` (the workflow's `defer_approval`, for a caller that
runs cursor-approve's axes after this round): an APPROVE outcome still reports
``pass``, but posts NO review and resolves NO thread — it withdraws this
identity's own earlier marked approvals instead, exactly as a no-decision round
does, so cursor-approve's ``approve-external`` is the only thing that ever
approves and no severity-only approval can satisfy branch protection while the
axes judge (or after a failed run that never reaches them). It also dismisses
this identity's own earlier REQUEST_CHANGES, which a posted APPROVE would have
superseded. A withdrawal that fails, or a head/base/label change since the read,
downgrades the gate as on the posting path. REQUEST_CHANGES is unaffected: it
approves nothing.

Trust model: every signal here — findings, panel status, judge status — is model
output over the PR's own content, so a diff that prompt-injects the panel and
judge can steer the round to an approval. The recorded SHA is mutable too — a
Expand Down Expand Up @@ -742,6 +754,8 @@ def cmd_decide(args) -> int:
if event == NONE:
emit(f"ℹ️ **Auto-approve: no decision** — {'; '.join(reasons)}.")
return withdraw_own_approvals(args)
if event == APPROVE and (getattr(args, "defer_approval", "") or "").strip().lower() == "true":
return defer_to_cursor_approve(args, reasons[0])

body = render_body(event, reasons, threshold, blocking, args.commit_sha, args.base_ref)
if event == APPROVE and not REVIEWED_SHA_RE.search(body):
Expand Down Expand Up @@ -821,6 +835,72 @@ def cmd_decide(args) -> int:
return 0


def defer_to_cursor_approve(args, reason: str) -> int:
"""`--defer-approval true` on an APPROVE outcome: post nothing, keep the gate.

The gate stays `pass` for cursor-approve, whose decide approves (and resolves
threads) only once its axes agree — unless one of the steps below says this
round can no longer stand behind it, exactly as the posting path would.
"""
emit(f"ℹ️ **Auto-approve: deferred** — {reason}; approval is left to cursor-approve.")
# Also clears an approval this identity posted before defer was switched on.
# One that cannot be withdrawn keeps satisfying branch protection while the
# axes judge, so the gate must not read `pass` over it (same as a failed POST).
rc = withdraw_own_approvals(args, DEFERRED_MESSAGE)
if rc:
set_output("approve_gate", GATE_UNTRUSTED)
# Posting path: the APPROVE event supersedes this identity's earlier
# REQUEST_CHANGES. Nothing is posted here, so dismiss those instead — else a
# fixed High keeps vetoing the merge until cursor-approve approves, which it
# never does on a red axis. Failing to is red but withholds nothing.
if dismiss_own_change_requests(args):
rc = 1
# Same post-decision re-check the posting path runs: a push, retarget or
# `needs-human-review` label landing since the read must not leave `pass`.
try:
pr_now = read_pr(args.repo, args.pr_number)
head_now, base_now = pr_head_base(pr_now)
labelled_now = has_label(pr_now, HUMAN_REVIEW_LABEL)
except (RuntimeError, ValueError):
head_now = base_now = None # unknown → treat as moved
labelled_now = False
if head_now != args.commit_sha or base_now != args.base_ref:
set_output("approve_gate", GATE_UNTRUSTED)
emit("ℹ️ **Auto-approve: deferred round superseded** — the PR head or base moved.")
elif labelled_now:
set_output("approve_gate", GATE_CAPPED)
emit(f"ℹ️ **Auto-approve: deferred round superseded** — the PR was labelled `{HUMAN_REVIEW_LABEL}`.")
return rc


def dismiss_own_change_requests(args) -> int:
"""Dismiss this identity's own unedited, marked REQUEST_CHANGES reviews.
An edited one is someone else's words (see _stale_approvals) and stays."""
login = (args.approver_login or "").strip().lower()
if not login:
return 0
try:
ids = [r["id"] for r in list_reviews(args.repo, args.pr_number)
if r.get("state") == "CHANGES_REQUESTED" and not r.get("edited")
and APPROVE_MARKER in (r.get("body") or "")
and (r.get("user") or {}).get("login", "").lower() == login]
except (RuntimeError, ValueError) as e:
print(f"::warning::Could not list reviews to withdraw an earlier request for changes: {annotation_cause(e, 'unknown error')}")
return 1
failed = []
for rid in ids:
try:
dismiss(args.repo, args.pr_number, rid, PASSED_MESSAGE)
except RuntimeError as e:
failed.append(f"{rid}: {annotation_cause(e, 'unknown error')}")
if ids:
emit(f"Auto-approve: withdrew {len(ids) - len(failed)}/{len(ids)} earlier request(s) for changes by {args.approver_login}.")
if failed:
print(f"::warning::Could not withdraw {len(failed)} earlier request(s) for changes ({'; '.join(failed)}). {DISMISS_PERMISSION_HINT}")
return 1
return 0


DISMISS_PERMISSION_HINT = (
"Dismissing a review needs an identity allowed to dismiss reviews on this branch: "
"pull-requests: write is not enough when branch protection restricts dismissals "
Expand Down Expand Up @@ -1035,6 +1115,8 @@ def withdraw_own_approvals(args, message: str = "", head_sha=None, live_base=Non
STALE_MESSAGE = "New commits pushed — cursor-review auto-approve withdrawn until the next review round."
BASE_CHANGED_MESSAGE = "The base branch changed — cursor-review auto-approve withdrawn until the next review round."
UNTRUSTED_MESSAGE = "The latest cursor-review round could not be trusted to approve — auto-approve withdrawn until a round that can."
DEFERRED_MESSAGE = "cursor-review defers approval to cursor-approve — auto-approve withdrawn until its axes agree."
PASSED_MESSAGE = "The latest cursor-review round passed its severity threshold — request for changes withdrawn; approval is left to cursor-approve."
HUMAN_REVIEW_MESSAGE = f"The PR was labelled `{HUMAN_REVIEW_LABEL}` — cursor-review auto-approve withdrawn."


Expand Down Expand Up @@ -1604,10 +1686,12 @@ def cmd_approve_external(args) -> int:

def cmd_withdraw(args) -> int:
"""cursor-approve.yml's start phase: withdraw this identity's own marked
approvals before the axes run. cursor-review's `decide` has ALREADY approved
when it reports `approve_gate == 'pass'`, so without this the axes would
judge a PR that is approved for their whole run, and branch protection or
auto-merge could land it before a red axis withdrew the approval."""
approvals before the axes run. Unless the caller passes cursor-review
`defer_approval: true` (``--defer-approval``), its `decide` has ALREADY
approved when it reports `approve_gate == 'pass'`, so without this the axes
would judge a PR that is approved for their whole run, and branch protection
or auto-merge could land it before a red axis withdrew the approval. With
defer on it is a backstop."""
if not (args.approver_login or "").strip():
print("::error::--approver-login is empty; refusing to run without an identity to withdraw approvals for")
return 2
Expand All @@ -1634,6 +1718,8 @@ def main() -> int:
# `<slug>[bot]`, else github-actions[bot]). On APPROVE, only threads it
# started are auto-resolved; empty = resolve nothing.
d.add_argument("--poster-login", default="")
# `true` = report the gate but never post an APPROVE (see the docstring).
d.add_argument("--defer-approval", default="")
s = sub.add_parser("dismiss-stale")
s.add_argument("--repo", required=True)
s.add_argument("--pr-number", required=True)
Expand Down
125 changes: 125 additions & 0 deletions .github/cursor-review/tests/test_auto_approve.py
Original file line number Diff line number Diff line change
Expand Up @@ -1724,6 +1724,131 @@ def test_counts_are_logged(self):
self.assertIn("resolved 1, skipped-human 1, skipped-unbadged 1, skipped-above-threshold 1", lines[-1])


class DeferApprovalTest(unittest.TestCase):
"""`--defer-approval true`: the gate is reported, but only cursor-approve approves."""

def run_decide(self, defer, findings=(), reviews=(), fail_put=False, pr_reads=()):
self.writes = []
self.resolved = []
later_reads = list(pr_reads) # PR payloads after the first read, in order

def fake_gh(args, payload=None):
if args[:2] == ["api", "-X"]:
self.writes.append((args[2], args[3], payload))
if args[2] == "PUT" and fail_put:
raise RuntimeError("gh api failed: 403 dismissals restricted")
return '{"id": 99}' if args[2] == "POST" else "{}"
if args[:2] == ["api", "graphql"]:
return graphql_reviews(list(reviews))
pr = {"head": {"sha": SHA}, "base": {"ref": "main"}}
if getattr(fake_gh, "read", False) and later_reads:
pr = later_reads.pop(0)
fake_gh.read = True
return json.dumps(pr)

with tempfile.TemporaryDirectory() as d:
fpath, dpath, out = (os.path.join(d, n) for n in ("c.json", "pr.patch", "out"))
with open(fpath, "w") as f:
json.dump({"findings": list(findings), "panel": PANEL_OK}, f)
with open(dpath, "w") as f:
f.write(DIFF)
open(out, "w").close()
args = argparse.Namespace(threshold="low", findings=fpath, repo="o/r", pr_number="1",
commit_sha=SHA, judge_status="ok", delivered="true",
ungated="0", approver_login="cursor-approver",
reviewed_diff=dpath, base_ref="main", poster_login=POSTER)
if defer is not None:
args.defer_approval = defer
with mock.patch.dict(os.environ, {"GITHUB_OUTPUT": out}), \
mock.patch.object(AA, "gh", fake_gh), \
mock.patch.object(AA, "open_thread_severities", lambda *a: []), \
mock.patch.object(AA, "resolve_eligible_threads", lambda *a: self.resolved.append(a)), \
mock.patch.object(AA, "emit", lambda *a: None):
rc = AA.cmd_decide(args)
return rc, read_outputs(out).get("approve_gate")

def test_a_passing_round_posts_nothing_and_resolves_nothing(self):
rc, gate = self.run_decide("true")
self.assertEqual((rc, gate, self.writes, self.resolved), (0, AA.GATE_PASS, [], []))

def test_earlier_marked_approvals_by_the_approver_are_withdrawn(self):
own = {"id": 7, "user": {"login": "cursor-approver"}, "state": "APPROVED",
"commit_id": SHA, "body": AA.APPROVE_MARKER}
human = {"id": 8, "user": {"login": "alice"}, "state": "APPROVED", "commit_id": SHA, "body": "lgtm"}
rc, gate = self.run_decide("true", reviews=[own, human])
self.assertEqual((rc, gate), (0, AA.GATE_PASS))
self.assertEqual([(m, path) for m, path, _ in self.writes],
[("PUT", "repos/o/r/pulls/1/reviews/7/dismissals")])
self.assertEqual(self.writes[0][2]["message"], AA.DEFERRED_MESSAGE)
self.assertEqual(self.resolved, [])

def test_a_failed_withdrawal_downgrades_the_gate(self):
own = {"id": 7, "user": {"login": "cursor-approver"}, "state": "APPROVED",
"commit_id": SHA, "body": AA.APPROVE_MARKER}
rc, gate = self.run_decide("true", reviews=[own], fail_put=True)
self.assertEqual((rc, gate), (1, AA.GATE_UNTRUSTED))

def test_own_marked_change_requests_are_dismissed(self):
own = {"id": 5, "user": {"login": "cursor-approver"}, "state": "CHANGES_REQUESTED",
"commit_id": SHA, "body": AA.APPROVE_MARKER}
edited = dict(own, id=6, edited=True)
unmarked = dict(own, id=9, body="please fix")
other = dict(own, id=10, user={"login": "alice"})
rc, gate = self.run_decide("true", reviews=[own, edited, unmarked, other])
self.assertEqual((rc, gate), (0, AA.GATE_PASS))
self.assertEqual([(m, path) for m, path, _ in self.writes],
[("PUT", "repos/o/r/pulls/1/reviews/5/dismissals")])
self.assertEqual(self.writes[0][2]["message"], AA.PASSED_MESSAGE)

def test_a_failed_change_request_dismissal_is_red_but_keeps_the_gate(self):
own = {"id": 5, "user": {"login": "cursor-approver"}, "state": "CHANGES_REQUESTED",
"commit_id": SHA, "body": AA.APPROVE_MARKER}
rc, gate = self.run_decide("true", reviews=[own], fail_put=True)
self.assertEqual((rc, gate), (1, AA.GATE_PASS))

def test_a_change_since_the_read_downgrades_the_gate(self):
moved = {"head": {"sha": "b" * 40}, "base": {"ref": "main"}}
retargeted = {"head": {"sha": SHA}, "base": {"ref": "dev"}}
labelled = {"head": {"sha": SHA}, "base": {"ref": "main"},
"labels": [{"name": AA.HUMAN_REVIEW_LABEL}]}
for pr, want in ((moved, AA.GATE_UNTRUSTED), (retargeted, AA.GATE_UNTRUSTED),
(labelled, AA.GATE_CAPPED), ("not a dict", AA.GATE_UNTRUSTED)):
with self.subTest(pr=pr):
rc, gate = self.run_decide("true", pr_reads=[pr])
self.assertEqual((rc, gate, self.writes), (0, want, []))

def test_defer_is_read_case_and_whitespace_insensitively(self):
for defer in ("True", " true ", "TRUE"):
with self.subTest(defer=defer):
rc, gate = self.run_decide(defer)
self.assertEqual((rc, gate, self.writes, self.resolved), (0, AA.GATE_PASS, [], []))

def test_request_changes_is_still_posted(self):
rc, gate = self.run_decide("true", findings=[finding("high")])
self.assertEqual((rc, gate), (0, AA.GATE_FAIL))
self.assertEqual([(m, p["event"]) for m, _, p in self.writes], [("POST", AA.REQUEST_CHANGES)])

def test_off_still_approves_and_resolves(self):
for defer in (None, "", "false"):
with self.subTest(defer=defer):
rc, gate = self.run_decide(defer)
self.assertEqual((rc, gate), (0, AA.GATE_PASS))
self.assertEqual([(m, p["event"]) for m, _, p in self.writes], [("POST", AA.APPROVE)])
self.assertEqual(len(self.resolved), 1)

def test_the_workflow_passes_the_input_to_decide(self):
with open(WORKFLOW_PATH, encoding="utf-8") as f:
src = f.read()
declared = src[src.index("\n defer_approval:\n"):]
declared = declared[: declared.index("\n max_rounds:\n")]
self.assertIn("type: boolean", declared)
self.assertIn("default: false", declared)
step = src[src.index("- name: Auto-approve decision"):]
step = step[: step.index("\n\n dismiss-stale-approval:")]
self.assertIn("DEFER_APPROVAL: ${{ inputs.defer_approval }}", step)
self.assertIn('--defer-approval "$DEFER_APPROVAL"', step)


class AutoResolveWiringTest(unittest.TestCase):
"""The workflow passes the findings poster's login to `decide`."""

Expand Down
8 changes: 5 additions & 3 deletions .github/workflows/cursor-approve.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,11 @@ name: Cursor approve
# passed (`approve_gate == 'pass'`), then call this TWICE:
#
# phase: start — before the axis jobs (they `needs:` it): withdraws this
# identity's own approvals — cursor-review's decide has
# ALREADY approved when it reports approve_gate == pass, and
# that approval must not stand while the axes judge — then
# identity's own approvals — unless cursor-review ran with
# `defer_approval: true` (recommended: then this phase's
# decide is the only approver), its decide has ALREADY
# approved when it reports approve_gate == pass, and that
# approval must not stand while the axes judge — then
# writes the status card (every axis pending, or "Round
# limit reached" when cursor-review reported
# approve_gate == capped).
Expand Down
Loading
Loading