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
17 changes: 13 additions & 4 deletions .github/scripts/fork-head-gate-workflow.test.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
against every fork workflow, in fork-contracts.test.py (head-gate).
"""

import json
import os
import pathlib
import re
Expand All @@ -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 = []
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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:
Expand Down
6 changes: 5 additions & 1 deletion docs/fork/gate-trust.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
41 changes: 29 additions & 12 deletions fork-ci/actions/head-check/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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).

Expand Down Expand Up @@ -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
Expand Down
9 changes: 6 additions & 3 deletions fork-ci/actions/head-check/gate-caller.example.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
25 changes: 13 additions & 12 deletions fork-ci/actions/head-check/head_gate.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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'

Expand Down Expand Up @@ -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():
Expand All @@ -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):
Expand Down
Loading
Loading