diff --git a/.github/scripts/fork-head-gate-workflow.test.py b/.github/scripts/fork-head-gate-workflow.test.py index a94ca70da2ca7..d63d4a4ae2c26 100644 --- a/.github/scripts/fork-head-gate-workflow.test.py +++ b/.github/scripts/fork-head-gate-workflow.test.py @@ -1,5 +1,6 @@ -"""Checks .github/workflows/fork-head-gate.yml and its example caller (fork-ci/actions/head-check/gate-caller.example.yml): -the step scripts are run as Actions runs them, the wiring is read from the files. +"""Checks .github/workflows/fork-head-gate.yml, its example caller (fork-ci/actions/head-check/gate-caller.example.yml) +and the review trigger the caller listens to (review-trigger.example.yml, issue #88): the step scripts are run as +Actions runs them, the wiring is read from the files. python3 .github/scripts/fork-head-gate-workflow.test.py @@ -20,6 +21,7 @@ root = pathlib.Path(__file__).resolve().parents[2] 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" text = WORKFLOW.read_text() wf = yaml.safe_load(text) failures = [] @@ -199,16 +201,31 @@ def args(*a): check("prs: the event and the number go on as they are (an empty number is the backfill)", r.returncode == 0 and r.stdout.startswith(args("-I", "-B", "toolkit/fork-ci/actions/head-check/head_gate.py", "prs", "--repo", "o/p", "--event", "workflow_dispatch", "--pr", "", - "--event-sha", "") + "\n"), r.stdout) + "--event-sha", "", "--run-event", "", "--run-sha", "", "--run-repo", "", + "--run-branch=") + "\n"), r.stdout) r = run(prs, REPO="o/p", EVENT="pull_request_target", PR="7", EVENT_SHA="ab" * 20) check("prs: the head the event carries goes on too (used only when the pull request read fails every try)", r.returncode == 0 and r.stdout.startswith(args("-I", "-B", "toolkit/fork-ci/actions/head-check/head_gate.py", "prs", "--repo", "o/p", "--event", "pull_request_target", "--pr", - "7", "--event-sha", "ab" * 20) + "\n"), r.stdout) -check("prs: the event comes from the run and the number from the caller", + "7", "--event-sha", "ab" * 20, "--run-event", "", "--run-sha", "", + "--run-repo", "", "--run-branch=") + "\n"), r.stdout) +r = run(prs, REPO="o/p", EVENT="workflow_run", PR="", RUN_EVENT="pull_request_review", RUN_SHA="cd" * 20, + RUN_REPO="f/p", RUN_BRANCH="-x y") +check("prs: a review trigger's run goes on as its head (event, sha, repository, branch); a branch is one --run-branch=", + r.returncode == 0 and r.stdout.startswith(args("-I", "-B", "toolkit/fork-ci/actions/head-check/head_gate.py", + "prs", "--repo", "o/p", "--event", "workflow_run", "--pr", "", + "--event-sha", "", "--run-event", "pull_request_review", + "--run-sha", "cd" * 20, "--run-repo", "f/p", + "--run-branch=-x y") + "\n"), r.stdout) +check("prs: the event comes from the run and the number from the caller; a workflow_run's head is GitHub's field of " + "the finished run, never its outputs", (prs.get("env") or {}) == {"GH_TOKEN": "${{ github.token }}", "REPO": "${{ github.repository }}", "EVENT": "${{ github.event_name }}", "PR": "${{ inputs.pr }}", - "EVENT_SHA": "${{ github.event.pull_request.head.sha }}"}, str(prs.get("env"))) + "EVENT_SHA": "${{ github.event.pull_request.head.sha }}", + "RUN_EVENT": "${{ github.event.workflow_run.event }}", + "RUN_SHA": "${{ github.event.workflow_run.head_sha }}", + "RUN_REPO": "${{ github.event.workflow_run.head_repository.full_name }}", + "RUN_BRANCH": "${{ github.event.workflow_run.head_branch }}"}, str(prs.get("env"))) eguard, target, drift, token, start, judge, finish = (tsteps + [{}] * 9)[2:9] check("gate: the Environment is checked again right before the token, without the secret's presence", @@ -284,8 +301,9 @@ def args(*a): # --- the example caller --------------------------------------------------------------------------------------------- ex = yaml.safe_load(EXAMPLE.read_text()) eon = ex.get(True, ex.get("on")) or {} -check("example: it runs on pull_request_target, issue_comment and workflow_dispatch only (never pull_request)", - set(eon) == {"pull_request_target", "issue_comment", "workflow_dispatch"}, str(set(eon))) +check("example: it runs on pull_request_target, issue_comment, workflow_run and workflow_dispatch only (never " + "pull_request, never a review event: those run the pull request's own copy)", + set(eon) == {"pull_request_target", "issue_comment", "workflow_run", "workflow_dispatch"}, str(set(eon))) check("example: every change of the head, the draft state and the title or base starts it", set((eon.get("pull_request_target") or {}).get("types") or []) >= {"opened", "synchronize", "reopened", "ready_for_review", "converted_to_draft", "edited"}) @@ -306,13 +324,15 @@ 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) -check("example: an issue comment that is not on a pull request starts nothing", - ejob.get("if") == "github.event_name != 'issue_comment' || github.event.issue.pull_request") +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")) 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", set(ew) <= set(inputs) and required <= set(ew), f"{sorted(ew)} vs {sorted(inputs)}") -check("example: the pull request is the event's number, as text, from all three events", +check("example: the pull request is the event's number, as text (none on a workflow_run: the gate looks it up)", ew.get("pr") == "${{ format('{0}', github.event.pull_request.number || github.event.issue.number || inputs.pr) }}") needed = {} for j in jobs.values(): @@ -322,6 +342,67 @@ def args(*a): all(["none", "read", "write"].index((ejob.get("permissions") or {}).get(s, "none")) >= ["none", "read", "write"].index(lv) for s, lv in needed.items()), str(needed)) +# --- the review trigger and the caller's workflow_run (issue #88) --------------------------------------------------- +trigger_text = TRIGGER.read_text() +tr = yaml.safe_load(trigger_text) +ton = tr.get(True, tr.get("on")) or {} +wr = eon.get("workflow_run") or {} +check("example: workflow_run of the review trigger, by its name, when its run completed", + wr == {"workflows": [tr.get("name")], "types": ["completed"]} and tr.get("name") == "Head gate review trigger", + str(wr)) +check("trigger: a review submitted, edited or dismissed and an inline review comment created, edited or deleted, " + "nothing else", + ton == {"pull_request_review": {"types": ["submitted", "edited", "dismissed"]}, + "pull_request_review_comment": {"types": ["created", "edited", "deleted"]}}, str(ton)) +tjobs = tr.get("jobs") or {} +tsteps_ = [s for j in tjobs.values() for s in (j.get("steps") or [])] +check("trigger: no token, no secrets, no Environment, no other workflow, no action: one job that only finishes", + tr.get("permissions") == {} and len(tjobs) == 1 + and all(j.get("permissions") == {} and not ({"environment", "uses", "secrets", "needs", "services", + "container"} & set(j)) for j in tjobs.values()) + and len(tsteps_) == 1 and set(tsteps_[0]) == {"name", "shell", "run"} + and "${{" not in str(tsteps_[0].get("run")) and "secrets" not in trigger_text.replace("no secrets", "") + and "checkout" not in trigger_text, str(tjobs)) +r = bash(tsteps_[0].get("run", "exit 1") if tsteps_ else "exit 1", {}) +check("trigger: its one step finishes (the caller starts only on a run that succeeded)", r.returncode == 0, r.stderr) +tconc = tr.get("concurrency") or {} +check("trigger: a burst on one pull request leaves one run (per pull request, the older ones cancelled)", + tconc == {"group": "head-gate-review-trigger-${{ github.event.pull_request.number }}", "cancel-in-progress": True}, + str(tconc)) + +econc = ejob.get("concurrency") or {} +check("example: the caller is never cancelled half-way (a cancel would post a failure on the head)", + econc.get("cancel-in-progress") is False, str(econc)) + + +def caller_group(event, run_id, sha="", workflow_ref="o/p/.github/workflows/gate.yml@refs/heads/main"): + """The caller's concurrency group as GitHub renders it (`a && b || c` of non-empty strings).""" + m = re.fullmatch(r"\$\{\{ github\.event_name == 'workflow_run' && format\('([^']*)', github\.workflow_ref, " + r"github\.event\.workflow_run\.head_sha\) \|\| format\('([^']*)', github\.run_id\) \}\}", + str(econc.get("group"))) + if not m: + return None + if event == "workflow_run": + return m.group(1).replace("{0}", workflow_ref).replace("{1}", sha) + return m.group(2).replace("{0}", str(run_id)) + + +check("example: the caller's group is read here as GitHub reads it", caller_group("push", 1) is not None, + str(econc.get("group"))) +if caller_group("push", 1) is not None: + burst = [(("review", i), caller_group("workflow_run", i, H)) for i in range(20)] + lost = cancelled_by_queue(burst) + check("example: a burst of 20 review trigger runs on one head: the first judges, the newest waits and judges, the " + "18 in between are dropped while they wait", + sorted(lost) == [("review", i) for i in range(1, 19)], str(lost)) + mixed = [(("review", 0), caller_group("workflow_run", 100, H)), (("comment", 1), caller_group("issue_comment", 101)), + (("review", 2), caller_group("workflow_run", 102, H)), (("push", 3), caller_group("pull_request_target", 103)), + (("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", + lost == [("review", 2)], str(lost)) + if failures: print(f"\n{len(failures)} failed") sys.exit(1) diff --git a/.github/workflows/fork-head-gate.yml b/.github/workflows/fork-head-gate.yml index 0d4be052faac4..ce24022a22a86 100644 --- a/.github/workflows/fork-head-gate.yml +++ b/.github/workflows/fork-head-gate.yml @@ -1,8 +1,10 @@ # Fork only. The head check as a gate (fork-ci/actions/head-check/README.md, "The gate"): head_check's rules on a bare # repository, posted as one check run of the project's own gate App, so a ruleset can require that check from that # App alone and no workflow file of a pull request can meet it. -# A caller on the default branch runs it on pull_request_target, issue_comment and workflow_dispatch (the README's -# example caller, gate-caller.example.yml) and passes `secrets: inherit`. The gate's code comes from this workflow's +# A caller on the default branch runs it on pull_request_target, issue_comment, workflow_dispatch and workflow_run of +# the review trigger (the README's example caller, gate-caller.example.yml, and review-trigger.example.yml) and passes +# `secrets: inherit`. On a workflow_run the pull request is looked up by the finished run's head (GitHub's fields of +# the run, never its outputs). The gate's code comes from this workflow's # own commit (job.workflow_repository and job.workflow_sha), never from the caller's tree, and nothing of the pull # request is ever checked out: the pull request is data. Only the gate job may use the Environment that holds the App # key, only after the guard job proved that key can be nowhere else. A check run belongs to a head, not to a pull @@ -98,7 +100,15 @@ jobs: EVENT: ${{ github.event_name }} PR: ${{ inputs.pr }} EVENT_SHA: ${{ github.event.pull_request.head.sha }} - run: python3 -I -B toolkit/fork-ci/actions/head-check/head_gate.py prs --repo "$REPO" --event "$EVENT" --pr "$PR" --event-sha "$EVENT_SHA" + RUN_EVENT: ${{ github.event.workflow_run.event }} + RUN_SHA: ${{ github.event.workflow_run.head_sha }} + RUN_REPO: ${{ github.event.workflow_run.head_repository.full_name }} + RUN_BRANCH: ${{ github.event.workflow_run.head_branch }} + # --run-branch=: a branch is the pusher's text, so it can never be read as an option. + run: | + python3 -I -B toolkit/fork-ci/actions/head-check/head_gate.py prs --repo "$REPO" --event "$EVENT" --pr "$PR" \ + --event-sha "$EVENT_SHA" --run-event "$RUN_EVENT" --run-sha "$RUN_SHA" --run-repo "$RUN_REPO" \ + --run-branch="$RUN_BRANCH" - name: Fail when no token can be made (no Environment) if: steps.guard.outputs.guard == '' shell: bash diff --git a/docs/fork/gate-trust.md b/docs/fork/gate-trust.md index eb8ec59291e73..4f7ab796a0e0f 100644 --- a/docs/fork/gate-trust.md +++ b/docs/fork/gate-trust.md @@ -44,7 +44,8 @@ check runs (`head_check_app`, [pr-queue](../../fork-ci/actions/pr-queue/README.m - **Lens comments.** A lens comment is only as good as the people allowed to post it (the config's `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 do not start it (see the README's "Run again after a review"). + comments start it through the review trigger, except when that does not run (see the README's "Run + again after a review"). - **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 5d93decd10b3c..0f1021dfd95fe 100644 --- a/fork-ci/actions/head-check/README.md +++ b/fork-ci/actions/head-check/README.md @@ -201,7 +201,8 @@ trusted, not only helpful ([issue 34](https://github.com/scuttletoby/t3code/issu How it works: - A caller on the default branch ([`gate-caller.example.yml`](gate-caller.example.yml)) - runs on `pull_request_target`, `issue_comment` and `workflow_dispatch`. + runs on `pull_request_target`, `issue_comment`, `workflow_dispatch` and + `workflow_run` of the review trigger (see "Run again after a review"). For a pull request into the default branch GitHub takes that file from the default branch, so a pull request that edits it changes nothing for its own run. The caller passes `secrets: inherit` (see "What it does not stop"). @@ -279,7 +280,9 @@ Setup (the repository owner's steps; nothing here creates them): 4. Copy the example caller to `.github/workflows/` on the default branch, fill in the check name, config path and required lenses (at least one, unless the config's `review` block is in `enforce`: then the path rules name them and - the input may be empty), and pin the release. + the input may be empty), and pin the release. Copy + [`review-trigger.example.yml`](review-trigger.example.yml) next to it, + unchanged (the caller names it by its `name`). 5. Dispatch it once without a number (the backfill), so open pull requests get the check under its name. 6. Bind the required check to the App: in a ruleset, the required status @@ -299,17 +302,51 @@ request. The same holds for the `review` block's path rules and for switching its `mode` from `shadow` to `enforce`: each open pull request is judged by the new rules at its next run, so dispatch the backfill right after the change. -**Run again after a review.** Reviews and inline diff comments -(`pull_request_review`, `pull_request_review_comment`) do not start the gate, -though the rules count them (a lens may post as a review or on a line). GitHub -runs those two events from the pull request's own merge commit, not from the -default branch: the pull request's copy of the caller runs, the Environment -(default branch only) refuses it, and it could never post. After a lens posts -as a review or on a line of the diff, or deletes one, 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 it anyway. A trusted way to -run on reviews is open: -[issue 88](https://github.com/scuttletoby/t3code/issues/88). +**Run again after a review.** The rules count reviews and inline diff +comments (a lens may post as a review or on a line), so a review submitted, +edited or dismissed and an inline comment written, edited or deleted run the +gate again, through two workflows +([issue 88](https://github.com/scuttletoby/t3code/issues/88)): + +- GitHub runs `pull_request_review` and `pull_request_review_comment` from + the pull request's own merge commit, not from the default branch, so the + caller cannot listen to them itself: the pull request's copy would run, and + the Environment (default branch only) would refuse it. The review trigger + ([`review-trigger.example.yml`](review-trigger.example.yml)) listens to them + instead. It does nothing but finish: no token, no secrets, nothing checked + out. Of a burst on one pull request only the newest run finishes (the older + ones are cancelled). +- The caller runs on `workflow_run` of it (`completed`, and only a run that + succeeded). `workflow_run` runs from the default branch, so the Environment + 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. +- 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. + +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 +name, but the caller only learns "look at this head again", which any issue +comment on the pull request can already say. A run from a fork carries the +fork as its head repository, so a fork that copies another pull request's +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. + +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 +only together with a gate release that knows `workflow_run`: an older gate +refuses that event (its guard job fails, nothing is posted). **Runs again, stops half-way, old state.** Every way a run can end leaves the head "not passed" unless it judged the head and the head passed. @@ -344,6 +381,10 @@ head "not passed" unless it judged the head and the head passed. gate. - The head is unknown: on an issue comment or a dispatch with a number, the 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). - 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 e10e8b3e9cee5..79531ba3d74e7 100644 --- a/fork-ci/actions/head-check/gate-caller.example.yml +++ b/fork-ci/actions/head-check/gate-caller.example.yml @@ -1,7 +1,8 @@ # An example caller of the head gate (README.md, "The gate"). Copy it to .github/workflows/ on the project's default # branch and fill in the CAPITALS. It runs from the default branch's copy whatever a pull request changes, and gives -# the pull request to the gate as a number, nothing more. Reviews and inline review comments start no run (README.md, -# "Run again after a review"): an issue comment, a push or a dispatch does. +# the pull request to the gate as a number, nothing more. Reviews and inline review comments start it through the +# review trigger (review-trigger.example.yml, copied next to this file; README.md, "Run again after a review"): on its +# finished run the gate looks the pull request up by that run's head. name: Head gate on: @@ -9,6 +10,9 @@ on: types: [opened, synchronize, reopened, ready_for_review, converted_to_draft, edited] issue_comment: types: [created, edited, deleted] + workflow_run: + workflows: [Head gate review trigger] # review-trigger.example.yml's name + types: [completed] workflow_dispatch: inputs: pr: @@ -20,8 +24,17 @@ permissions: {} jobs: gate: - # A comment on an issue that is no pull request starts nothing. - if: github.event_name != 'issue_comment' || github.event.issue.pull_request + # 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). + if: >- + (github.event_name != 'issue_comment' || github.event.issue.pull_request) && + (github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success') + # 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. + 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 uses: scuttletoby/t3code/.github/workflows/fork-head-gate.yml@ # ci/vN permissions: contents: read diff --git a/fork-ci/actions/head-check/head_gate.py b/fork-ci/actions/head-check/head_gate.py index c48d81c9ba5aa..45c854b571dd6 100644 --- a/fork-ci/actions/head-check/head_gate.py +++ b/fork-ci/actions/head-check/head_gate.py @@ -4,7 +4,7 @@ A pull request can change the workflow its own head check runs in, and that job reports as GitHub Actions, which any workflow file of the pull request can also report as. The gate runs from the default branch's workflow -(pull_request_target, issue_comment, workflow_dispatch), with code from the fork's pinned release, reads the pull +(pull_request_target, issue_comment, workflow_dispatch, and workflow_run of the review trigger), with code from the fork's pinned release, reads the pull request only as data, and posts with a key that lives only in an Environment that only the default branch may use. A ruleset that binds the required check to the gate App's id then counts this check run and nothing else. @@ -21,8 +21,8 @@ GitHub does not take the first write (start), no token can be made (no key, no App, no Environment), the guard job cannot read the Environment (it may not exist; when REST says 5xx or a rate limit every try, GraphQL, with its own rate limit, may still show it exists), the head is unknown (on an event that does not carry it, the pull -request read fails every try and so does git's refs/pull/N/head), the backfill cannot list the open pull requests, a -step before start fails, or the run never reaches start. +request read fails every try and so does git's refs/pull/N/head), the backfill or a review run's lookup cannot list +the open pull requests, a step before start fails, or the run never reaches start. guard GITHUB_OUTPUT guard=ok when the key can only be the Environment's: no repository or organisation secret of its name (REPO_SECRET_PRESENT=true|false: the workflow passes only whether one is set), the Environment exists, and its deployment branches are exactly one rule, the default branch. Else exit 1 and guard=fail @@ -35,7 +35,10 @@ failure, so a pass it had cannot survive to a later ready, retarget or reopen), or, for a dispatch without 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). + 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. 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 @@ -61,7 +64,8 @@ import head_check # noqa: E402 import pr_queue # noqa: E402 (../pr-queue, put on the path by head_check) -EVENTS = ('pull_request_target', 'issue_comment', 'workflow_dispatch') +EVENTS = ('pull_request_target', 'issue_comment', 'workflow_dispatch', 'workflow_run') +REVIEW_EVENTS = ('pull_request_review', 'pull_request_review_comment') # what starts the review trigger (#88) MAX_PRS = 256 # a matrix runs at most 256 jobs MAX_SAME_HEAD = 20 # open, ready pull requests one head may have; each is judged RETRY_SECONDS = head_check.RETRY_SECONDS # between two tries of a write @@ -75,6 +79,8 @@ 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 +BRANCH_MAX = 255 SERVER = 'https://github.com' @@ -301,15 +307,76 @@ def pull_head_by_git(repo, number, env): return None, why -def prs(repo, event, pr_text, gh, out, env, event_sha='', git_head=None): +def review_run_pr(repo, run, gh, out): + """([{pr, sha}] or [], None) or (None, why) for a workflow_run of the review trigger. `run`: {event, sha, repo, + branch}, GitHub's fields of the finished run (github.event.workflow_run: event, head_sha, + head_repository.full_name, head_branch). The number is read from the API: the open pull requests whose head + branch is that branch of that repository, kept when their head is the run's sha. Never from the run's outputs, + artifacts or names: whatever the run did (a pull request can change its own copy of the trigger), it only says + "look at this head again", as an issue comment can.""" + event, sha = str(run.get('event') or ''), str(run.get('sha') or '').strip().lower() + head_repo, branch = str(run.get('repo') or ''), str(run.get('branch') or '') + if event not in REVIEW_EVENTS: + out(f'nothing to judge: the run that finished was started by {event or "no event"!r}, not by a review or an ' + f'inline review comment ({", ".join(REVIEW_EVENTS)})') + return [], None + if not (pr_queue.SHA.fullmatch(sha) and pr_queue.REPO_RE.fullmatch(head_repo) and 0 < len(branch) <= BRANCH_MAX + and branch.isprintable()): + out("nothing to judge: the run does not name a head (head sha, head repository, head branch); dispatch the " + 'gate with the pull request number') + return [], None + owner = urllib.parse.quote(head_repo.split('/')[0], safe='') + query = (f'repos/{repo}/pulls?state=open&per_page=100&head={owner}:' + + urllib.parse.quote(branch, safe='/')) + r = read(gh, '--paginate', query, '--jq', HEAD_JQ) + if r.returncode != 0: + return None, f'could not list the open pull requests with the head of the review run: {said(r)}' + matches = [] + for line in r.stdout.splitlines(): + try: + n, draft, 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) + 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(): + matches.append(n) + where = f'{sha} of {head_repo} branch {branch!r}' + if not matches: + 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 + + +def prs(repo, event, pr_text, gh, out, env, event_sha='', git_head=None, run=None): """The heads to judge, [{pr, sha}] (see the module's doc). target and judge judge a head as a whole; the pr only names the job. When the pull request read fails every try: `event_sha`, the head the event carries - (pull_request_target), else `git_head(repo, number, env)` (the CLI's: pull_head_by_git).""" + (pull_request_target), else `git_head(repo, number, env)` (the CLI's: pull_head_by_git). On a workflow_run: `run`, + see review_run_pr.""" pr_text, event_sha = (pr_text or '').strip(), (event_sha or '').strip().lower() if event not in EVENTS: return refuse(out, env, f'refused on a {event or "unnamed"} event: the gate runs only on {", ".join(EVENTS)}') if pr_text and not NUMBER.fullmatch(pr_text): return refuse(out, env, f'{pr_text!r} is not a pull request number') + if event == 'workflow_run': + if pr_text: + return refuse(out, env, f'a workflow_run that names #{pr_text}: on a workflow_run the pull request comes ' + "only from the API, by the run's head") + if not pr_queue.REPO_RE.fullmatch(repo): + return refuse(out, env, f'--repo {repo!r} is not owner/name') + found, why = review_run_pr(repo, run or {}, gh, out) + if found is None: + return refuse(out, env, why, 'Nothing was posted: an older check run on the head stays until the next ' + 'event on the pull request, or a dispatch with its number.') + set_output(env, prs=json.dumps(found, separators=(',', ':'))) + return 0 if not pr_text and event != 'workflow_dispatch': return refuse(out, env, f'a {event} event that names no pull request') if not pr_queue.REPO_RE.fullmatch(repo): @@ -730,6 +797,10 @@ def cli(argv=None, env=None, gh=gh_run, out=print, decide=head_check.decide, sle s.add_argument('--event', required=True) s.add_argument('--pr', default='') s.add_argument('--event-sha', default='', help='the head the event carries, used when the pull request read fails') + s.add_argument('--run-event', default='', help='workflow_run: the event that started the finished run') + s.add_argument('--run-sha', default='', help="workflow_run: the run's head sha") + s.add_argument('--run-repo', default='', help="workflow_run: the run's head repository, owner/name") + s.add_argument('--run-branch', default='', help="workflow_run: the run's head branch (give it as --run-branch=X)") run_arguments(sub.add_parser('target')) j = sub.add_parser('judge') run_arguments(j) @@ -756,7 +827,8 @@ def cli(argv=None, env=None, gh=gh_run, out=print, decide=head_check.decide, sle return guard(a.repo, a.environment, a.secret_name, env.get('REPO_SECRET_PRESENT', ''), a.environment_only, gh, out, env) if a.cmd == 'prs': - return prs(a.repo, a.event, a.pr, gh, out, env, a.event_sha, git_head) + return prs(a.repo, a.event, a.pr, gh, out, env, a.event_sha, git_head, + run={'event': a.run_event, 'sha': a.run_sha, 'repo': a.run_repo, 'branch': a.run_branch}) if a.cmd == 'target': return target(a, gh, out, env) if a.cmd == 'judge': diff --git a/fork-ci/actions/head-check/head_gate.test.py b/fork-ci/actions/head-check/head_gate.test.py index 51b149e188e94..8deae77d2613a 100644 --- a/fork-ci/actions/head-check/head_gate.test.py +++ b/fork-ci/actions/head-check/head_gate.test.py @@ -66,8 +66,9 @@ def __call__(self, *a, stdin=None): if isinstance(v, Seq): v = v.pop(0) if len(v) > 1 else v[0] return v if isinstance(v, types.SimpleNamespace) else answer(0, json.dumps(v)) - if a[:2] == ('api', '--paginate') and a[3:] == ('--jq', G.LIST_JQ) and a[2] in self.lists: - v = self.lists[a[2]] # the open pull requests: (number, draft, head sha, base ref), one JSON line each + if a[:2] == ('api', '--paginate') and a[3:] in (('--jq', G.LIST_JQ), ('--jq', getattr(G, 'HEAD_JQ', None))) \ + and a[2] in self.lists: + v = self.lists[a[2]] # the open pull requests, one JSON line each: LIST_JQ's or HEAD_JQ's fields return v if isinstance(v, types.SimpleNamespace) else answer(0, ''.join(json.dumps(x) + '\n' for x in v)) if self.rest: return self.rest(*a) @@ -331,7 +332,7 @@ def found(self): return found def test_the_events_one_open_ready_pull_request_into_the_default_branch(self): - for event in G.EVENTS: + for event in ('pull_request_target', 'issue_comment', 'workflow_dispatch'): # workflow_run: ReviewRun with self.subTest(event=event): code, out, _ = self.prs(event, '7', self.pull()) self.assertEqual((code, self.found()), (0, [{'pr': 7, 'sha': self.H}]), out) @@ -430,6 +431,107 @@ def test_an_unreadable_or_odd_listing_is_refused(self): self.assertEqual((code, self.file('output')), (1, None), out) +# --- prs on a workflow_run: the review trigger's run (issue #88) ----------------------------------------------------- +class ReviewRun(Files, unittest.TestCase): + """A review or an inline review comment starts the review trigger (review-trigger.example.yml); its finished run + starts the caller on workflow_run, from the default branch. The pull request comes from the API, by the run's head + sha, head repository and head branch (all GitHub's), never from the run's outputs, artifacts or names.""" + H, OTHER = 'a1' * 20, 'b2' * 20 + RUN = {'event': 'pull_request_review', 'sha': 'a1' * 20, 'repo': REPO, 'branch': 'feature/x'} + + def query(self, owner, branch): + return f'repos/{REPO}/pulls?state=open&per_page=100&head={owner}:{branch}' + + def review(self, rows=(), run=None, pr='', query=None): + run = {**self.RUN, **(run or {})} + query = query or self.query(run['repo'].split('/')[0], run['branch']) + lists = {query: rows if isinstance(rows, types.SimpleNamespace) else list(rows), + f'repos/{REPO}/pulls?state=open&per_page=100': [(1, False, self.H, 'main')]} # never the backfill + gh, out = Api(lists=lists), [] + code = G.prs(REPO, 'workflow_run', pr, gh, out.append, self.env, run=run) + return code, '\n'.join(out), gh + + def found(self): + found = json.loads(self.outputs().get('prs', 'null')) + os.remove(self.env['GITHUB_OUTPUT']) + return found + + 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)] + 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')], + 'one paged read, by head: never the backfill') + + 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)]): + 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_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 + 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 + 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'}, + query=self.query(REPO.split('/')[0], 'a%26b%3Dc%23d%2Be%25f')) + self.assertEqual((code, self.found()), (0, [{'pr': 12, 'sha': self.H}]), out) + + def test_a_run_of_another_event_or_with_odd_fields_judges_nothing_and_reads_nothing(self): + for run in ({'event': 'pull_request'}, {'event': 'push'}, {'event': ''}, {'sha': 'abc'}, {'sha': ''}, + {'repo': ''}, {'repo': 'no-slash'}, {'branch': ''}, {'branch': 'a\nb'}, {'branch': 'x' * 256}): + with self.subTest(run=run): + code, out, gh = self.review(run=run) + self.assertEqual((code, self.found(), gh.calls), (0, [], []), out) + self.assertIn('nothing to judge', out) + + 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')): + 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)] + answers = [] + for _ in range(3): + code, out, _ = self.review(rows) + answers.append((code, self.found())) + self.assertEqual(answers, [(0, [{'pr': 12, 'sha': self.H}])] * 3) + + def test_the_cli_takes_the_run_fields_and_a_branch_that_starts_with_a_dash(self): + seen = [] + with unittest.mock.patch.object(G, 'prs', lambda *a, **k: seen.append((a, k)) or 0): + self.assertEqual(G.cli(['prs', '--repo', REPO, '--event', 'workflow_run', '--pr', '', '--event-sha', '', + '--run-event', 'pull_request_review_comment', '--run-sha', self.H, + '--run-repo', REPO, '--run-branch=-x'], env=self.env), 0) + self.assertEqual(seen[0][1]['run'], {'event': 'pull_request_review_comment', 'sha': self.H, 'repo': REPO, + 'branch': '-x'}) + + # --- target --------------------------------------------------------------------------------------------------------- class Target(Files, unittest.TestCase): H, TIP = 'a1' * 20, 'e5' * 20 diff --git a/fork-ci/actions/head-check/review-trigger.example.yml b/fork-ci/actions/head-check/review-trigger.example.yml new file mode 100644 index 0000000000000..694dd4e2ba31e --- /dev/null +++ b/fork-ci/actions/head-check/review-trigger.example.yml @@ -0,0 +1,30 @@ +# The head gate's review trigger (README.md, "Run again after a review"). Copy it to .github/workflows/ on the +# project's default branch next to the gate caller, unchanged: the caller's `workflow_run` names it by this `name`. +# GitHub runs review events from the pull request's own merge commit, so this file may be the pull request's own copy: +# it does nothing but finish, has no token and no secrets, and the caller trusts nothing it says. Its finished run only +# tells the caller (from the default branch) "look at this head again"; the gate reads the pull request by the run's +# head from the API, as an issue comment would make it read it. +name: Head gate review trigger + +on: + pull_request_review: + types: [submitted, edited, dismissed] + pull_request_review_comment: + types: [created, edited, deleted] + +permissions: {} + +# A burst of reviews or line comments on one pull request: only the newest run finishes; the caller starts on it. +concurrency: + group: head-gate-review-trigger-${{ github.event.pull_request.number }} + cancel-in-progress: true + +jobs: + finish: + runs-on: ubuntu-latest + timeout-minutes: 2 + permissions: {} + steps: + - name: Finish (the head gate's caller runs on this run's workflow_run) + shell: bash + run: echo "A review or an inline review comment changed; the head gate judges this head again."