From 7c39c24c44bbf7b2c7bdcc35b32a261608422a0b Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Tue, 17 Nov 2026 22:22:22 +0100 Subject: [PATCH] head gate: #375 follow-ups (one head two PRs, docs, caller if, case test) - A review run whose head two open pull requests share (one branch into two bases) now judges that head once, under the lowest number, and logs the others, instead of judging nothing (a withdrawn lens read could leave a stale pass). README and log text no longer say "each number". - HEAD_JQ no longer reads the unused .draft (preflight fails a draft's head). - The caller example's `if` skips a review trigger run that no review started, before a guard job starts. - Docs: withdrawing a lens read (README, gate-trust.md), which groups drop which runs, and the merge-conflict case in the fallback list. - Tests: a repo name in another case (kills the surviving mutant), two and three PRs on one head, one closed half-way, the listing's fields. Part of #379, #88 Co-Authored-By: Claude Opus 5.5 --- .../scripts/fork-head-gate-workflow.test.py | 17 ++++-- docs/fork/gate-trust.md | 6 ++- fork-ci/actions/head-check/README.md | 41 ++++++++++----- .../head-check/gate-caller.example.yml | 9 ++-- fork-ci/actions/head-check/head_gate.py | 25 ++++----- fork-ci/actions/head-check/head_gate.test.py | 52 ++++++++++++++----- 6 files changed, 105 insertions(+), 45 deletions(-) diff --git a/.github/scripts/fork-head-gate-workflow.test.py b/.github/scripts/fork-head-gate-workflow.test.py index 424d3e82a422b..61d3cb3012659 100644 --- a/.github/scripts/fork-head-gate-workflow.test.py +++ b/.github/scripts/fork-head-gate-workflow.test.py @@ -9,6 +9,7 @@ against every fork workflow, in fork-contracts.test.py (head-gate). """ +import json import os import pathlib import re @@ -22,6 +23,7 @@ WORKFLOW = root / ".github/workflows/fork-head-gate.yml" EXAMPLE = root / "fork-ci/actions/head-check/gate-caller.example.yml" TRIGGER = root / "fork-ci/actions/head-check/review-trigger.example.yml" +GATE_PY = root / "fork-ci/actions/head-check/head_gate.py" text = WORKFLOW.read_text() wf = yaml.safe_load(text) failures = [] @@ -330,10 +332,16 @@ def args(*a): and "Needed:" in EXAMPLE.read_text()) check("example: no pass-drafts anywhere (a draft's check run would count for a ready pull request at its head)", "pass-drafts" not in EXAMPLE.read_text() and "pass-drafts" not in text) +REVIEW_EVENTS = re.search(r"^REVIEW_EVENTS = \(([^)]*)\)", GATE_PY.read_text(), re.M) +REVIEW_EVENTS = re.findall(r"'([a-z_]+)'", REVIEW_EVENTS.group(1)) if REVIEW_EVENTS else [] check("example: an issue comment that is not on a pull request starts nothing, nor a review trigger run that did " - "not succeed (a newer one replaced it)", - ejob.get("if") == "(github.event_name != 'issue_comment' || github.event.issue.pull_request) && " - "(github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success')", ejob.get("if")) + "not succeed (a newer one replaced it) or that another event started (#379: skipped before a guard job " + "starts; the events are head_gate's REVIEW_EVENTS)", + REVIEW_EVENTS == ["pull_request_review", "pull_request_review_comment"] + and ejob.get("if") == "(github.event_name != 'issue_comment' || github.event.issue.pull_request) && " + "(github.event_name != 'workflow_run' || (github.event.workflow_run.conclusion == 'success' && " + "contains(fromJSON('" + json.dumps(REVIEW_EVENTS, separators=(",", ":")) + "'), " + "github.event.workflow_run.event)))", ejob.get("if")) ew = ejob.get("with") or {} required = {k for k, v in inputs.items() if v.get("required")} check("example: it gives only inputs the gate has, and every required one", @@ -406,7 +414,8 @@ def caller_group(event, run_id, sha="", workflow_ref="o/p/.github/workflows/gate (("review", 4), caller_group("workflow_run", 104, H)), (("other-head", 5), caller_group("workflow_run", 105, "b2" * 20)), (("other-gate", 6), caller_group("workflow_run", 106, H, "o/p/.github/workflows/gate2.yml@refs/heads/main"))] lost = cancelled_by_queue(mixed) - check("example: review runs never drop a comment's, a push's, another head's or another caller's run", + check("example: in the caller's group, review runs never drop a comment's, a push's, another head's or another " + "caller's run (the gate job's own group is per head: a newer job there reads the newest state)", lost == [("review", 2)], str(lost)) if failures: diff --git a/docs/fork/gate-trust.md b/docs/fork/gate-trust.md index 4f7ab796a0e0f..afd509caec4f4 100644 --- a/docs/fork/gate-trust.md +++ b/docs/fork/gate-trust.md @@ -45,7 +45,11 @@ check runs (`head_check_app`, [pr-queue](../../fork-ci/actions/pr-queue/README.m `lens_author_associations`). Who may post them once agents use App tokens is open (lens identity). - **Stale answers.** The gate judges the comments that exist when it runs. Reviews and inline diff comments start it through the review trigger, except when that does not run (see the README's "Run - again after a review"). + again after a review"). The trigger is a convenience, not a guard: withdrawing a lens read (deleting + an inline lens comment, editing a review) runs the gate again only through the pull request's own + copy of the trigger, and another pull request may be able to cancel those runs through the shared + concurrency group name (not tested live). A stale answer, which can be a pass, then stays. To + withdraw a lens read, post an issue comment on the pull request or dispatch the gate. - **Ordinary CI jobs.** A pull request can still weaken an ordinary job of its own workflow. The gate catches that only through review: the reviewers read the exact head, and the gate cannot be rewritten. diff --git a/fork-ci/actions/head-check/README.md b/fork-ci/actions/head-check/README.md index 0f1021dfd95fe..1d45c47369161 100644 --- a/fork-ci/actions/head-check/README.md +++ b/fork-ci/actions/head-check/README.md @@ -321,15 +321,20 @@ gate again, through two workflows allows it. The gate takes no number from that run: it reads the open pull requests whose head branch is the run's head branch in the run's head repository and keeps the one whose head is the run's head sha (all three - are GitHub's fields of the run, never its outputs, artifacts or names). One - match is judged like an issue comment on it. None (closed or merged since, - or the head moved on: the push ran the gate already) or more than one (one - branch into two bases): nothing is judged and the log says why; dispatch - the gate with each number. + are GitHub's fields of the run, never its outputs, artifacts or names). A + match is judged like an issue comment on it. More than one (one branch into + two bases, so every match has the same head): the gate judges a head, not a + pull request, so the lowest number judges it once for all of them, and the + log names the others. None (closed or merged since, or the head moved on: + the push ran the gate already): nothing is judged and the log says why. - Review trigger runs on one head wait in one group per caller: one judges, the newest waits, the ones in between are dropped while they wait. A run is - never cancelled half-way (that would post a failure on the head). Other - events are never dropped by them. + never cancelled half-way (that would post a failure on the head). In the + caller, every other event has a group of its own, so a review run never + drops it there. The gate job's own group (per head and check name) is + shared by all events, so a later review run's gate job can replace a + comment's or a push's gate job still waiting on the same head. That is + harmless: the newer job reads the newest state of the same head. Why a pull request gains nothing from this: it can change its own copy of the trigger (that copy is the one that runs), or add any workflow of the same @@ -340,11 +345,23 @@ head sha finds only its own pull request, and the head is judged as a whole anyway. A pull request that removes or breaks its copy only stops runs on itself. +The trigger is a convenience, not a guard. Withdrawing a lens read (deleting +an inline lens comment, editing a review) runs the gate again only through +the pull request's own copy of the trigger, which the pull request controls. +Concurrency groups are shared across the repository, so another pull +request's workflow may be able to cancel those runs through the same group +name (not tested live). Until a push, an issue comment or a dispatch, the old +answer, which can be a pass, stays. To withdraw a lens read, post an issue +comment on the pull request or dispatch the gate: the review trigger may not +run. + Fallback: when the trigger does not run (a fork's run waiting for approval, a review posted with a workflow's `GITHUB_TOKEN`, which starts no workflow, -or a project that has not copied it yet), post an issue comment on the pull -request or dispatch the gate with its number. A new push, ready or draft, a -base change and any issue comment start the gate anyway. Copy the new caller +a pull request with a merge conflict, on which GitHub runs no +`pull_request*` workflow, or a project that has not copied it yet), post an +issue comment on the pull request or dispatch the gate with its number. A new +push, ready or draft, a base change and any issue comment start the gate +anyway. Copy the new caller only together with a gate release that knows `workflow_run`: an older gate refuses that event (its guard job fails, nothing is posted). @@ -383,8 +400,8 @@ head "not passed" unless it judged the head and the head passed. pull request read and git's `refs/pull/N/head` both fail every try. - A review trigger's run whose pull request cannot be found: the list of open pull requests with its head fails every try (the guard job fails), or - no open pull request, or more than one, has its head (nothing to judge, - the log says which). + no open pull request has its head (nothing to judge, the log says why). + More than one is no such case: the lowest number judges the head once. - The backfill cannot list the open pull requests after its tries, or finds more than 256 heads. Dispatch again (or once per pull request). - A step before start fails for a reason of GitHub or the runner, never diff --git a/fork-ci/actions/head-check/gate-caller.example.yml b/fork-ci/actions/head-check/gate-caller.example.yml index d12b104f42bed..cbe3815af808c 100644 --- a/fork-ci/actions/head-check/gate-caller.example.yml +++ b/fork-ci/actions/head-check/gate-caller.example.yml @@ -25,13 +25,16 @@ permissions: {} jobs: gate: # A comment on an issue that is no pull request starts nothing, nor does a review trigger run that did not finish - # (a newer one on the same pull request replaced it). + # (a newer one on the same pull request replaced it) or that no review started (a workflow of the same name run by + # a push or a pull request's own event: skipped here, before a guard job starts). if: >- (github.event_name != 'issue_comment' || github.event.issue.pull_request) && - (github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success') + (github.event_name != 'workflow_run' || (github.event.workflow_run.conclusion == 'success' && + contains(fromJSON('["pull_request_review","pull_request_review_comment"]'), github.event.workflow_run.event))) # Review trigger runs of one head (a burst of reviews or line comments): one judges, the newest waits, the ones in # between are dropped while they wait. Never cancelled half-way (that would post a failure). Every other event has - # a group of its own, so it is never dropped. + # a group of its own here, so a review run never drops it in this group. (The gate job's own group, per head, is + # shared by all events: a newer job there replaces a waiting one and reads the newest state of the same head.) concurrency: group: ${{ github.event_name == 'workflow_run' && format('head-gate-review-{0}-{1}', github.workflow_ref, github.event.workflow_run.head_sha) || format('head-gate-run-{0}', github.run_id) }} cancel-in-progress: false diff --git a/fork-ci/actions/head-check/head_gate.py b/fork-ci/actions/head-check/head_gate.py index 45c854b571dd6..7f4f284d22c81 100644 --- a/fork-ci/actions/head-check/head_gate.py +++ b/fork-ci/actions/head-check/head_gate.py @@ -36,9 +36,10 @@ one, the head of every open pull request (the backfill, paged, one entry per head). When the read fails every try: the head the event carries (--event-sha), else refs/pull/N/head by git (not the REST API, so not its rate limit). On a workflow_run (the review trigger's run finished, README.md "Run again after a - review"): no number is taken; the one open pull request whose head is the run's head sha from the run's - head repository and branch (--run-*, GitHub's fields of the run), read from the API. None, or more than - one: nothing to judge (a log line says why). A run of another event: nothing to judge. + review"): no number is taken; the open pull requests whose head is the run's head sha from the run's + head repository and branch (--run-*, GitHub's fields of the run), read from the API. More than one (one + branch into two bases): the lowest number judges the head once, the log names the others. None, or a run + of another event: nothing to judge (a log line says why). target before any token: post=false only for bad arguments. Else post=true: the head gets a failure (judge writes it) when the guard did not pass, on a re-run (run attempt 2 or later), for a caller that is not the default branch's current one or does not pin this gate release, for a lens list with a name that names no lens, for @@ -79,7 +80,7 @@ GATE_WORKFLOW = 'fork-head-gate.yml' GATE_FILES = ('.github/workflows/' + GATE_WORKFLOW, 'fork-ci/actions/head-check', 'fork-ci/actions/pr-queue') LIST_JQ = '.[] | [.number, .draft, .head.sha, .base.ref] | @json' -HEAD_JQ = '.[] | [.number, .draft, .head.sha, .head.repo.full_name] | @json' # head.repo is null for a deleted fork +HEAD_JQ = '.[] | [.number, .head.sha, .head.repo.full_name] | @json' # head.repo is null for a deleted fork BRANCH_MAX = 255 SERVER = 'https://github.com' @@ -334,10 +335,10 @@ def review_run_pr(repo, run, gh, out): matches = [] for line in r.stdout.splitlines(): try: - n, draft, head, from_repo = json.loads(line) + n, head, from_repo = json.loads(line) except (ValueError, TypeError): return None, 'GitHub listed something that is not a pull request' - if not (type(n) is int and n > 0 and isinstance(draft, bool) and isinstance(head, str) + if not (type(n) is int and n > 0 and isinstance(head, str) and pr_queue.SHA.fullmatch(head.lower()) and (from_repo is None or isinstance(from_repo, str))): return None, 'GitHub listed something that is not a pull request' if head.lower() == sha and isinstance(from_repo, str) and from_repo.lower() == head_repo.lower(): @@ -347,12 +348,12 @@ def review_run_pr(repo, run, gh, out): out(f'nothing to judge: no open pull request has the head {head_check.escape(where)} (closed or merged since, ' 'or the head moved on: its push ran the gate)') return [], None - if len(matches) > 1: - out(f'nothing to judge: {len(matches)} open pull requests have the head {head_check.escape(where)} ' - f'({", ".join(f"#{n}" for n in sorted(matches))}); dispatch the gate with each number') - return [], None - out(f'review run: #{matches[0]} has the head {head_check.escape(where)}') - return [{'pr': matches[0], 'sha': sha}], None + # One branch into two bases: every match has this head, and the gate judges a head, not a pull request (preflight + # lists every open pull request with it again; the number only names the job). So it is judged once. + first, others = min(matches), sorted(set(matches) - {min(matches)}) + also = f'; #{first} judges it for {", ".join(f"#{n}" for n in others)} too' if others else '' + out(f'review run: #{first} has the head {head_check.escape(where)}{also}') + return [{'pr': first, 'sha': sha}], None def prs(repo, event, pr_text, gh, out, env, event_sha='', git_head=None, run=None): diff --git a/fork-ci/actions/head-check/head_gate.test.py b/fork-ci/actions/head-check/head_gate.test.py index 7df8ec6bce07f..c558e97cfb853 100644 --- a/fork-ci/actions/head-check/head_gate.test.py +++ b/fork-ci/actions/head-check/head_gate.test.py @@ -459,7 +459,7 @@ def found(self): def test_the_one_open_pull_request_with_the_runs_head_is_judged(self): for event in G.REVIEW_EVENTS: with self.subTest(event=event): - rows = [(12, False, self.H.upper(), REPO), (13, False, self.OTHER, REPO)] + rows = [(12, self.H.upper(), REPO), (13, self.OTHER, REPO)] code, out, gh = self.review(rows, {'event': event}) self.assertEqual((code, self.found()), (0, [{'pr': 12, 'sha': self.H}]), out) self.assertEqual([c[0][2] for c in gh.calls], [self.query(REPO.split('/')[0], 'feature/x')], @@ -467,30 +467,51 @@ def test_the_one_open_pull_request_with_the_runs_head_is_judged(self): def test_no_open_pull_request_with_the_head_judges_nothing(self): # Empty: none open (closed or merged meanwhile), or the head moved on (the push ran the gate already). - for rows in ([], [(12, False, self.OTHER, REPO)], [(12, False, self.H, None)]): + for rows in ([], [(12, self.OTHER, REPO)], [(12, self.H, None)]): with self.subTest(rows=rows): code, out, _ = self.review(rows) self.assertEqual((code, self.found()), (0, []), out) self.assertIn('nothing to judge', out) self.assertIn('no open pull request', out) - def test_two_open_pull_requests_with_the_head_judge_nothing(self): # same branch into two bases: ask for a number - code, out, _ = self.review([(12, False, self.H, REPO), (14, True, self.H, REPO)]) - self.assertEqual((code, self.found()), (0, []), out) - self.assertIn('nothing to judge', out) - self.assertIn('#12, #14', out) + def test_two_open_pull_requests_with_the_head_judge_it_once(self): # #379: same branch into two bases + # The gate judges a head, not a pull request (preflight lists every open pull request with it again), so the + # lowest number judges it once for all of them; the others are named in the log. Nothing is skipped: a lens + # read withdrawn on one of them leaves no stale pass. Order of the listing, a third one: the same answer. + for rows in ([(12, self.H, REPO), (14, self.H, REPO)], [(14, self.H, REPO), (12, self.H.upper(), REPO)], + [(15, self.H, REPO), (14, self.H, REPO), (12, self.H, REPO), (13, self.OTHER, REPO)]): + with self.subTest(rows=rows): + code, out, _ = self.review(rows) + self.assertEqual((code, self.found()), (0, [{'pr': 12, 'sha': self.H}]), out) + self.assertNotIn('nothing to judge', out) + self.assertNotIn('each number', out) + others = ', '.join(f'#{n}' for n, h, _ in sorted(rows) if h.lower() == self.H and n != 12) + self.assertIn(f'#12 judges it for {others} too', out) + + def test_one_of_two_closed_half_way_judges_the_one_left(self): # stops half-way: the listing has the one left + for rows in ([(14, self.H, REPO)], [(12, self.H, REPO)]): + with self.subTest(rows=rows): + code, out, _ = self.review(rows) + self.assertEqual((code, self.found()), (0, [{'pr': rows[0][0], 'sha': self.H}]), out) + + def test_the_head_repository_is_compared_without_case(self): # GitHub names are case-insensitive + for run_repo, row_repo in ((REPO.upper(), REPO), (REPO, REPO.upper()), + ('Someone/T3code-Fork', 'someone/t3code-fork')): + with self.subTest(run=run_repo, row=row_repo): + code, out, _ = self.review([(31, self.H, row_repo)], {'repo': run_repo}) + self.assertEqual((code, self.found()), (0, [{'pr': 31, 'sha': self.H}]), out) def test_a_fork_head_is_looked_up_in_the_fork_and_a_forged_sha_elsewhere_never_matches(self): fork = {'repo': 'someone/t3code-fork', 'branch': 'main'} - rows = [(30, False, self.H, REPO), (31, False, self.H, 'someone/t3code-fork')] # 30: same sha, base repo + rows = [(30, self.H, REPO), (31, self.H, 'someone/t3code-fork')] # 30: same sha, base repo code, out, gh = self.review(rows, fork) self.assertEqual((code, self.found()), (0, [{'pr': 31, 'sha': self.H}]), out) self.assertEqual(gh.calls[0][0][2], self.query('someone', 'main')) - code, out, _ = self.review([(30, False, self.H, REPO)], fork) # only another repository's head has the sha + code, out, _ = self.review([(30, self.H, REPO)], fork) # only another repository's head has the sha self.assertEqual((code, self.found()), (0, []), out) def test_the_branch_is_one_query_value(self): # a branch name is the pusher's text - code, out, gh = self.review([(12, False, self.H, REPO)], {'branch': 'a&b=c#d+e%f'}, + code, out, gh = self.review([(12, self.H, REPO)], {'branch': 'a&b=c#d+e%f'}, query=self.query(REPO.split('/')[0], 'a%26b%3Dc%23d%2Be%25f')) self.assertEqual((code, self.found()), (0, [{'pr': 12, 'sha': self.H}]), out) @@ -502,20 +523,25 @@ def test_a_run_of_another_event_or_with_odd_fields_judges_nothing_and_reads_noth self.assertEqual((code, self.found(), gh.calls), (0, [], []), out) self.assertIn('nothing to judge', out) + def test_the_listing_reads_only_the_fields_it_uses(self): # #379: no draft (preflight fails a draft's head) + self.assertEqual(G.HEAD_JQ, '.[] | [.number, .head.sha, .head.repo.full_name] | @json') + def test_a_number_on_a_workflow_run_is_refused(self): # the number comes only from the API code, out, gh = self.review(pr='7') self.assertEqual((code, self.file('output'), gh.calls), (1, None, []), out) def test_an_unreadable_or_odd_listing_is_refused_and_posts_nothing(self): # stops half-way: an older check stays - for rows in (answer(1, '', 'gh: Server Error (HTTP 502)'), answer(0, 'x\n'), answer(0, '[12, false, "x", null]\n'), - answer(0, '[true, false, "' + self.H + '", null]\n'), answer(0, '[12, "no", "' + self.H + '", null]\n')): + for rows in (answer(1, '', 'gh: Server Error (HTTP 502)'), answer(0, 'x\n'), answer(0, '[12, "x", null]\n'), + answer(0, '[true, "' + self.H + '", null]\n'), answer(0, '[12, "' + self.H + '", 5]\n'), + answer(0, '[12, false, "' + self.H + '", null]\n'), # the old four-field row + answer(0, '[12, "' + self.H + '", "' + REPO + '", false]\n')): with self.subTest(rows=rows.stdout[:20]): code, out, gh = self.review(rows) self.assertEqual((code, self.file('output')), (1, None), out) self.assertIn('could not list', out) if rows.returncode else self.assertIn('not a pull request', out) def test_a_burst_of_runs_reads_the_same_answer_each_time(self): # runs again: reads only, the same answer - rows = [(12, False, self.H, REPO)] + rows = [(12, self.H, REPO)] answers = [] for _ in range(3): code, out, _ = self.review(rows)