Feat: Sweep approved fork PRs on a schedule

[ModeSevenIndustrialSolutions]

Summary

Closes #421

A caller of the reusable workflow that subscribes to schedule now gets the zero-touch fork flow: a maintainer approves in the ordinary way, and the next sweep transfers the change. Nobody has to comment @github2gerrit check. That comment still works, and is still the faster route.

on:
  schedule:
    - cron: "17 * * * *"

This builds on #454. The per-PR fan-out and the transfer record were the two pieces #421 said a correct sweep needed.

Commits

• Test: Share the reusable workflow test harness: a refactor that moves the expression evaluator and enumeration runner out of test_bulk_fan_out.py into tests/workflow_harness.py, so the new tests can reuse them. No assertion changes. test_precommit_mypy_pins now derives local test modules from the tracked files instead of a fixed list, so the next shared helper won't trip it either.
• Feat: Sweep approved fork PRs on a schedule: the feature.

#421's requirements, one by one

Each transfer is serialised against per-PR runs. A schedule fans out through the enumerate job exactly as a bulk dispatch does: one leg per PR, each in the concurrency group every event run for that PR uses. A sweep leg and a comment re-check for the same commit — the collision #421 thought likeliest — now queue instead of both creating a first Gerrit change.

The sweep visits only PRs the gate can block. A scheduled listing keeps a PR only when both of these hold:

• Its head is not known to be in this repository. This is head_repo_is_trusted's own rule: name for name, ignoring case. A head whose repository no longer exists (a deleted fork) is visited, because the gate applies to unresolved provenance.
• Some approving review covers its current head. The gate can't authorise without one, so this only drops PRs it would block anyway. Who approved, and whether changes are requested, are still for the leg's gate to decide. If GitHub truncates the review list, the PR is kept rather than guessed about.

Same-repository PRs, including every automation PR, never enter a scheduled sweep. Bulk dispatch still visits everything. A schedule has no cleanup leg, and a run with nothing to visit starts no jobs.

An already-transferred PR is not submitted again. Its leg reads the #419 record and stops. The record isn't read during enumeration, since that would mean reimplementing _sweep_can_skip's reading of the comment thread in jq.

Covered by tests, not just documented. See Validation below.

Tool side

schedule joins RECHECK_EVENTS, which gives a scheduled leg everything a comment re-check already has:

• UPDATE mode, so an existing change gains a patchset rather than a sibling.
• The create-missing fallback, so the first transfer isn't refused.
• The same-repository short-circuit, as a second line of defence behind the listing filter.

The existing parametrised tests over RECHECK_EVENTS now cover schedule automatically.

The composite action accepts PR_NUMBER on schedule, which is how a leg names its PR. Without one, or with 0, the action fails with an explanation rather than sweeping every PR in one job. A composite action can't start jobs, and one job over every PR is exactly the race #421 describes.

Trade-offs worth a reviewer's eye

• Repeated jobs. A PR that is approved but not yet transferred, or transferred but still open, gets a short job on every run until its head moves or it closes; the transfer record makes that job stop early. Hourly suits most projects, and the docs say so.
• Schedule suspension. GitHub suspends schedules in a public repo after 60 days without activity. The comment re-check is unaffected, and the docs note this.
• Listing query. The query now also fetches headRefOid, headRepository and up to 100 approving reviews per PR. That is still about 1 GraphQL point per page of 100 PRs.

Validation

• uv run pytest tests/: full suite passes.
• ruff, mypy and basedpyright are clean.
• prek passes on both commits (actionlint with shellcheck, yamllint, check-yaml, write-good, markdownlint, reuse, pytest), and gitlint passes.
• aislop ci --changes --base upstream/main: 100/100, nothing new.
• zizmor --persona auditor: no findings in github2gerrit.yaml; the 3 pre-existing ones in testing.yaml are untouched.
• tests/test_scheduled_sweep.py covers:
  • routing: a schedule starts a sweep, and the single job doesn't run;
  • the lock a scheduled leg shares with pull_request_target and comment runs, evaluated from the workflow's own expressions;
  • the listing filter case by case against the stubbed API: approved fork, same repo, case-only difference, deleted fork, unapproved, stale approval, truncated reviews, mixed pages, bulk dispatch unaffected;
  • the 256/257 matrix limit;
  • the action steps a scheduled leg passes through;
  • RECHECK_EVENTS membership.
• I mutation-tested each guard (10 mutations); every one fails at least one test.

As with #454, this hasn't run on real runners. After merge, adding a schedule trigger to testing.yaml's reusable-workflow job, which runs with G2G_NO_GERRIT, would exercise it safely.

[Copilot]

Copilot review overview

🔵 Needs a closer look

It introduces unattended Gerrit transfers and intricate workflow concurrency that warrant validation on real runners.

Review effort: Balanced
Findings: None

What changed in this PR

Adds scheduled, zero-touch processing of approved fork pull requests while preserving per-PR serialization and transfer idempotency.

Changes:

• Adds scheduled candidate enumeration and per-PR fan-out.
• Treats scheduled legs as privileged rechecks with validated PR numbers.
• Adds documentation and comprehensive workflow tests.

File	Description
.github/​workflows/​github2gerrit.yaml	Implements scheduled enumeration and fan-out.
action.yaml	Accepts validated scheduled sweep legs.
src/​github2gerrit/​models.py	Classifies schedules as recheck events.
README.md	Documents scheduled reusable-workflow usage.
docs/​features.md	Explains scheduling behavior and caveats.
tests/​workflow_harness.py	Provides shared workflow-test utilities.
tests/​test_scheduled_sweep.py	Covers filtering, locking, routing, and limits.
tests/​test_bulk_fan_out.py	Reuses the shared test harness.
tests/​test_precommit_mypy_pins.py	Recognizes test helper modules as first-party.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.