Skip to content

head gate: review trigger live check as a setup step, release note, warning on odd run fields (#379) - #650

Merged
scuttletoby merged 1 commit into
mainfrom
fix/379-head-gate-followups
Nov 20, 2026
Merged

scuttletoby merged 1 commit into
mainfrom
fix/379-head-gate-followups

Conversation

@scuttletoby

Copy link
Copy Markdown
Owner

Fixes #379

Each point of #379, checked against current main

Every existing refusal is kept. The only behaviour change is that one log line becomes a warning annotation. Exit code, outputs and what is judged or posted do not change.

Tests

  • fork-ci/actions/head-check/head_gate.test.py: 106 OK. The odd-fields test now also checks two things. Odd head fields give exactly one ::warning:: line. Another event gives no annotation, and no ::error:: appears in either case.
  • .github/scripts/fork-head-gate-workflow.test.py: all passed. Three new checks:
    • README setup step 8 is the live check: it posts a review, names the expected log line, the warning, the head=owner:branch filter and the fallback.
    • The warning text quoted in the README is head_gate.py's own text.
    • The release notes have a trigger entry whose Upgrade names both example files, workflow_run, if, concurrency, the old-pin refusal and setup step 8.
  • .github/scripts/fork-contracts.test.py: all passed.
  • .github/scripts/fork-gate-trust-docs.test.py: not run locally (a local guard refuses this script). The PR does not touch it, and CI runs it.
  • vp fmt --check on both changed Markdown files: clean.

Red first: with the new tests and the old head_gate.py, README and release notes, there were 7 failures in head_gate.test.py (one per odd-field case) and 3 FAILs in the workflow test. All are green with the change.

State question

  • Runs again: the lookup only reads, so a repeated review run with odd fields gives the same warning each time and judges nothing. The result is the same as before, now visible. The test runs ten such cases one after another on the same state.
  • Stops half-way: unchanged. The warning comes before any read, and nothing is listed or posted, so an older check run stays as it was.
  • Old state:
    • A caller pinned to ci/v15 to ci/v19 keeps the plain log line until it moves its pin. The release note says from which release the warning appears.
    • An older caller without the event clause still gets a plain log line for runs of other events (tested), so moving the pin adds no annotation noise.
  • Empty or missing state: missing fields are the case that now warns (tested: empty sha, repository and branch). A project with no trigger copied never runs on workflow_run. The note says that moving the pin alone breaks nothing.

General vs project

  • General (every repository that uses the fork-ci head gate): the warning, the README setup step and the release note.
  • Project: none in this repository. The live check itself is done once by whoever copies the trigger into a project, following setup step 8.

🤖 Generated with Claude Code

…arning on odd run fields (#379)

Items 1 to 7 of #379 are on main (#392, #406). Item 8, the live check, needs a project that
copies the trigger, so it becomes a written setup step (README step 8) and part of a new
release-notes entry for the trigger, which every ci/v15+ release ships without one. A review
run whose head fields are missing or odd now judges nothing with a ::warning:: instead of a
plain log line, so a live mismatch of GitHub's fields is seen rather than staying green.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

Review (lens B): SAFE

Head 1240f440aa. No blocking or major findings. The code change is one out() text in review_run_pr. Return value, exit code, outputs and every refusal are unchanged: the diff touches nothing else in head_gate.py. All CI checks are green.

What I checked

  • Tests: head_gate.test.py gives 106 OK. fork-head-gate-workflow.test.py passes.
  • Red first: with main's head_gate.py, README and release notes, the 3 new workflow checks fail. The old warning text fails 7 head_gate subtests.
  • Code mutants, all 7 killed:
    • warning changed back to a plain line
    • warning also on the other-event branch
    • ::warning:: changed to ::error::
    • fall through after the warning, so the listing runs
    • warning turned into a refusal
    • two annotations
    • isprintable dropped
  • Docs mutants:
    • Killed: warning text drift in the README, head=owner:branch dropped, `if` dropped from the notes, "setup step 8" dropped.
    • Survived: one, see minor 3.
  • Can this make a stale pass stick, skip a head that should be judged, or turn a refusal into a pass? No new path. The odd-fields branch judged nothing before and still does. Only the log level changed.
  • Items 1–7 of head gate review trigger: #375 follow-ups (two PRs one branch, docs, caller if, test gap, live check) #379 on main: each is present.
    • 1: min(matches) judged once, head_gate.py:357-367. "each number" is gone from the README.
    • 2: "post an issue comment or dispatch" in README:395 and docs/fork/gate-trust.md:46-52.
    • 3: the per-head group wording at README:374.
    • 4: the merge conflict in the fallback list at README:401.
    • 5: the event clause in gate-caller.example.yml:30-33.
    • 6: HEAD_JQ has 3 fields, pinned by a test.
    • 7: test_the_head_repository_is_compared_without_case.
  • Claim that ci/v15..ci/v19 ship the trigger: confirmed by file diff against main.
    • gate-caller.example.yml, review-trigger.example.yml and fork-head-gate.yml are identical at every one of those tags.
    • head_gate.py differs by one unrelated line (GIT_ATTR_NOSYSTEM).
    • ci/v14 has no trigger. Its EVENTS lacks workflow_run and goes to refuse(), so the note's "guard job fails, nothing is posted" is right. "First in ci/v15" is right.
  • Step 8 log line: review run: #N has the head … matches head_gate.py:362. The warning text is the code's own, and a test pins it.

Minor

  1. head_gate.py:327-333 (comment at 329) and README:323-333: some valid branch names are now classed as "odd", and the warning blames GitHub's fields.
    • The cause is branch.isprintable(). Git accepts branch names that Python calls not printable, for example a no-break space (feat/ x), a zero-width space, or an emoji with a zero-width joiner (fix-👨‍👩). I checked these with git check-ref-format --branch and str.isprintable().
    • A real review on such a PR now gets a warning that says GitHub's fields are not what the lookup expects. Step 8 then says "they differ: reviews then never run the gate again". That is the wrong diagnosis.
    • The same is likely when a fork's repository was deleted (head_repository null), so "a review run always has these fields" is not quite true.
    • This is not a safety problem: those heads were skipped before too, and the fallback covers them.
    • Fix: warn only when sha, repository or branch is missing or malformed. For a present branch that is only unusual, keep a plain line. Or say in the text "or the branch name has characters the gate does not look up; use the fallback".
  2. The likely failure mode stays a plain log line (README:327-331).
    • If GitHub's real fields or the head=owner:branch filter differ from the fakes, the probable symptom is "no open pull request has the head". That is a plain log line, and it is also the normal line when a PR closed or moved on.
    • The new warning covers only the missing-fields case, which practically never fires. So "makes a failed check visible" holds only for that case. Step 8 does name both symptoms, so a person doing the check will see it, but nothing alerts anyone afterwards.
    • Fine for this PR. Just do not count the annotation as a monitor.
  3. The old-pin refusal check is weak (.github/scripts/fork-head-gate-workflow.test.py:446). The check only looks for "pinned to an older release". Rewording "is refused" to "fails" in RELEASE-NOTES.md:258 survives. Add "is refused" or "guard job fails" to the words list.
  4. A pin on ci/v15..ci/v19 is told to move first (fork-ci/RELEASE-NOTES.md:255). "after the pin is at a release that has this entry": ci/v15..ci/v19 have the trigger but not this entry, so a project on them reads that it must move first. That is harmless (conservative). "at ci/v15 or later" would be exact.
  5. "Fixes head gate review trigger: #375 follow-ups (two PRs one branch, docs, caller if, test gap, live check) #379" and item 8.

@scuttletoby

Copy link
Copy Markdown
Owner Author

Review (lens A): SAFE

Head 1240f440aa. No blocking or major findings. Read-only review: own worktree, tests run only in temp dirs.

What changed in code: one out() text in review_run_pr (head_gate.py:332): a plain line becomes a ::warning::. The diff touches no return value and no condition. Both odd-field returns are still [], None. Exit code, prs output, the event guard, the sha, repo and branch checks, the listing, the match rules and every refuse are byte-identical to main. So nothing can now make a stale pass stick, skip a head that main judged, or turn a refusal into a pass. The text is constant (no run field in it), so it cannot inject an annotation.

Is a normal event now classed as odd? Another event (pull_request, push, empty) still gets the plain line, and that check runs first (head_gate.py:323). Letter case: the sha is lowered before the check, and REPO_RE accepts both cases. Fork runs carry the fork's full_name, which passes. A deleted head branch keeps its name in the run payload. The only real run I can think of that warns is in minor 2.

Items 1 to 7 of #379, checked on main:

  1. review_run_pr returns [{pr: min, sha}] once and logs the other numbers (head_gate.py:357-367).
  2. README "The trigger is a convenience…" (README:389-397) and docs/fork/gate-trust.md:46-52.
  3. README:370-377 (and the caller's comment).
  4. README:399-403 has the merge-conflict case.
  5. gate-caller.example.yml if has the workflow_run.event clause.
  6. HEAD_JQ has three fields, and the test pins it.
  7. test_the_head_repository_is_compared_without_case (head_gate.test.py:531). My case-sensitive mutant is now killed (3 failures).

All seven hold.

ci/v15..ci/v19 ship the trigger: checked by file content. At each of these tags, gate-caller.example.yml, review-trigger.example.yml and .github/workflows/fork-head-gate.yml are identical to main. head_gate.py differs only by the unrelated GIT_ATTR_NOSYSTEM line. ci/v14 has no trigger, so "First in ci/v15" is right. None of these tags is an ancestor of main, which confirms the PR's explanation of the earlier "contains neither".

Docs against the code:

  • Setup step 8 (README:323-333) quotes three texts that are head_gate.py's own: review run: #N has the head (:362), the warning (:332) and no open pull request has the head (:354). The head=owner:branch filter is the query at :336. The fallback is the existing "Run again after a review" section.
  • The release-notes Upgrade (RELEASE-NOTES:255-262) names exactly what ci/v14→main added to the caller: workflow_run, if and concurrency. Its old-pin claim is true: an older prs has no workflow_run in EVENTS, so it refuses.

Tests and mutants:

  • At the PR head: head_gate.test.py 106 OK, fork-head-gate-workflow.test.py all passed, fork-contracts.test.py all passed.
  • Red first: the new tests with main's head_gate.py, README and notes give 7 failures and 3 FAILs, as the PR body says.
  • Mutants, 11 of 11 killed:
    • warning back to a plain line
    • warning changed to ::error::
    • other-event line given the warning
    • odd fields returned as None (a refusal)
    • odd fields falling through to the listing
    • isprintable dropped
    • BRANCH_MAX dropped
    • warning text changed (killed by the workflow test)
    • case-sensitive repo compare
    • event guard off
    • the review run: #N has the head text changed

CI: gh pr checks 650 is all green: fork kit 1-3, as root, walls, lint, workflow lint, secret scan, fork-ci-result. The rest are skipped by path.

State question:

  • Runs again: read-only, so a repeat gives the same warning.
  • Stops half-way: the warning comes before any read or post.
  • Old caller (no event clause): a plain line, no new noise.
  • Old pin v15-v19: the plain line until the pin moves.
  • No trigger copied: never runs on workflow_run.

Minor

  1. "Fixes head gate review trigger: #375 follow-ups (two PRs one branch, docs, caller if, test gap, live check) #379" with item 8 not done (PR body; README:323). The PR is honest about it: the check cannot run in this repository, because no project has the caller and trigger. The warning plus setup step 8 make a failure visible at the first rollout, which is a fair stand-in. But head gate review trigger: #375 follow-ups (two PRs one branch, docs, caller if, test gap, live check) #379's own status comment (2026-11-20) said to keep the issue open until the live check is green. The PR's main reason, "head gate: reviews and inline review comments do not re-run the gate #88 has since been closed", was already true when that comment was written (head gate: reviews and inline review comments do not re-run the gate #88 closed 2026-11-17). After the merge, GitHub's real review-run fields stay unverified, and no open issue tracks that. This is the orchestrator's or owner's call. Either accept it as is, or say "Part of head gate review trigger: #375 follow-ups (two PRs one branch, docs, caller if, test gap, live check) #379" (or open a small "live check at first rollout" issue) so that it stays tracked.
  2. "A real review run always has these fields" is slightly too strong (head_gate.py:329-331, README:445-448). PLAUSIBLE, not tested: a review on a still-open PR whose head fork was deleted can give a run with a null head_repository. That run warns "GitHub's fields are not what the lookup expects", which is not the cause. It is harmless: it exits 0, judges nothing (nothing could be judged anyway) and changes nothing else. Suggested wording: "…or the head repository is gone".

Nits

  • Setup step 8 (README:328-331) names only the warning as the failure sign. A project still pinned at v15-v19 logs the old plain line instead. The positive check (the review run: line and a new check run) still catches it, and the Upgrade says to move the pin first, so this is fine. One clause ("older pins log it without the warning") would close the gap.
  • RELEASE-NOTES:245: the entry sits in the middle of a "newest first" list. Its only new behaviour (the "After ci/v19" sentence) is in the middle of the paragraph. A tag diff shows it anyway, so this is cosmetic.

🤖 Generated with Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant