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
1 change: 1 addition & 0 deletions .github/fork-ci-tests.txt
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
fork-ci/actions/docs-scope/docs-scope.test.py
fork-ci/actions/gradle-cache/gradle_cache.test.py
fork-ci/actions/job-changed/job-changed.test.py
fork-ci/actions/pr-queue/lens.test.py

# Upstream's tests, run where fork-tests.yml follows upstream's ci.yml.
.github/scripts/check-nightly-release.test.cjs run by .github/workflows/fork-tests.yml
Expand Down
31 changes: 31 additions & 0 deletions .github/scripts/fork-ci-tests.test.cjs
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
const assert = require("node:assert/strict");
const childProcess = require("node:child_process");
const fs = require("node:fs");
const os = require("node:os");
const path = require("node:path");
Expand Down Expand Up @@ -112,3 +113,33 @@ test("the composite actions' tests under fork-ci are found too, and a missing fo
fs.rmSync(root, { recursive: true, force: true });
}
});

test("an unlisted test under .github/scripts or fork-ci fails the run", () => {
const root = fs.mkdtempSync(path.join(os.tmpdir(), "fork-ci-tests-"));
try {
const write = (file, text) => {
fs.mkdirSync(path.dirname(path.join(root, file)), { recursive: true });
fs.writeFileSync(path.join(root, file), text);
};
const script = fs.readFileSync(require.resolve("./fork-ci-tests.cjs"));
write(".github/scripts/fork-ci-tests.cjs", script);
write(".github/fork-ci-tests.txt", "# nothing listed\n");
write(".github/scripts/s.test.sh", "");
write("fork-ci/actions/x/a.test.py", "");
const env = { ...process.env };
delete env.GITHUB_STEP_SUMMARY;
const run = childProcess.spawnSync("node", [".github/scripts/fork-ci-tests.cjs"], {
cwd: root,
env,
encoding: "utf8",
});
assert.equal(run.status, 1, run.stdout + run.stderr);
for (const file of [".github/scripts/s.test.sh", "fork-ci/actions/x/a.test.py"])
assert.ok(
run.stdout.includes(`${file} is not in .github/fork-ci-tests.txt`),
`${file} not reported: ${run.stdout}`,
);
} finally {
fs.rmSync(root, { recursive: true, force: true });
}
});
110 changes: 110 additions & 0 deletions fork-ci/actions/pr-queue/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
# pr-queue

A merge queue for a repository whose branch ruleset requires pull requests to be
up to date with their base branch. After each push to the base branch it brings
exactly one waiting pull request up to date, and it turns auto-merge back on
only for a head that holds exactly the change the review read.

This folder is built in four stacked pull requests:

1. the review rules and the config (`lens.py`, `config.py`): this part;
2. the queue itself (`pr_queue.py`);
3. armed pull requests that cannot merge (a red required check, or one that
ended without passing or never reported) are told once and passed over;
4. the "red only because the base was red" rule, the reusable workflow
`.github/workflows/fork-pr-queue.yml`, `action.yml` and the usage sections
of this file.

## Config

One JSON file in the project's repository. Unknown keys, a key written twice, a
missing required key, an empty `required_checks` or a value of the wrong type is
an error: the queue then exits non-zero and touches no pull request.

```json
{
"required_checks": ["build", "test", "review-check"],
"merge_method": "squash",
"delete_branch": true,
"bot_logins": ["coderabbitai", "github-actions", "copilot"],
"lens_author_associations": ["OWNER", "COLLABORATOR"],
"override": { "prefix": "tool ready --head", "author_association": "OWNER" },
"ready_command": "tool ready {pr}",
"push_command": "tool push",
"lens_format_doc": "docs/review.md, section Lens comments",
"head_check": "review-check"
}
```

| Key | Required | Meaning |
| -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `required_checks` | yes | Exactly the checks the branch ruleset requires. Not empty. |
| `merge_method` | yes | `merge`, `squash` or `rebase`: how auto-merge is turned back on. |
| `delete_branch` | yes | Whether auto-merge deletes the branch after merging. |
| `bot_logins` | yes | Logins whose comments never count as a lens. Any login ending in `[bot]` is a bot too. May be empty. |
| `lens_author_associations` | yes | Whose comments count as lens comments: GitHub's author association of the comment, from `OWNER`, `MEMBER`, `COLLABORATOR`. Everyone else's comments are ignored (Lens comments). `MEMBER` and `COLLABORATOR` do not mean write access: list only those whose holders may all vouch for a head. |
| `override` | yes | The comment that vouches for a head when the lenses read older commits: `<prefix> <40-hex sha>: <why>`, posted with this author association (`OWNER`, `MEMBER` or `COLLABORATOR`, with the same caveat) and never edited. |
| `ready_command` | yes | The command people run to re-arm a pull request after a lens read; `{pr}` is the number. Only quoted in the queue's comments. |
| `push_command` | yes | The command people run to push a fixed branch. Only quoted in comments. |
| `lens_format_doc` | yes | Where the project documents its lens comments. Only quoted in comments. |
| `head_check` | yes | The required check that fails a head no lens read; it must be one of `required_checks`. The queue acts only on pull requests that are behind: without this check, a push to an armed pull request that is already up to date merges unread. |
| `wait_seconds` | no | How long to wait for GitHub to show the updated head (default 60). |
| `poll_seconds` | no | How often to look meanwhile (default 5). |
| `list_limit` | no | How many open pull requests to read (default 50). |

## Lens comments

A review is posted as lens comments: one comment per review angle, whose
first line is its header.

```
lens: correctness · reviewer: <who> · read at: <sha>
```

`Lens:`, `**Lens:**`, `## lens:` and `- lens:` work too; the separator may be
`·`, `,`, `—` or nothing, and `<sha>` is the full 40-hex commit sha. A shorter
sha reads nothing: a force-push can bring a new commit with the same prefix. The
sha need not still be a commit of the pull request (a rebase drops it); the
queue re-arms only a head whose change is exactly the change read there. Each
lens's newest comment counts. The reviewed head is the one commit every lens's
newest read names, or a newer override comment's sha (config `override`). A
pull request with no lens comments is not reviewed, and the queue then vouches
only for the head it found.

Only comments and reviews that GitHub records as written by one of
`lens_author_associations` count: anyone can comment on a public repository,
so everyone else's comments are neither reads nor reports. The run log names
each lens-looking comment it ignored this way and its author association, so a
wrong `lens_author_associations` shows there. A lens comment edited after
posting, or hidden (minimized), reads nothing until that lens posts a new
comment: an edit can move `read at` to a head nobody read, and hiding old review
rounds must not make a reviewed pull request look unreviewed (the queue would
then vouch for whatever head it found). A lens a later round drops therefore
needs an override, or its old comment deleted. A hidden override counts
nothing. GitHub shows no hidden state for reviews, so a review counts as shown.

The grammar is fixed: a project writes its lens reports this way, it does not
configure another way. It fails closed. A comment that looks like a lens report
but is not exactly one valid read counts as a lens that read nothing, so the
queue never takes a reviewed pull request for an unreviewed one. Looking like a
report means any of: `lens:`, `read at`, `safe to merge`, a `## ... lens`
heading near the top, or two `covered:`/`checks:` lines. A comment that is no
report says so on its first line, `not a lens: ...`. That clears it unless one of
its lines is a lens header or a `lens:` field with a sha.

## Where the rules come from

`lens.py` is a port of a production queue's review rules, behaviour for
behaviour. `testdata/lens-corpus.jsonl` holds every call that project's lens
tests made to its copy, with that copy's answer; `lens.test.py` replays all of
them against `lens.py`. Logins and the project name in the corpus were
replaced, and the replaced corpus was checked against the source copy before it
was committed. A rule change here must keep the corpus green or say in its pull
request why a recorded answer changes.

The port differs on purpose in three ways, and the replay checks each recorded
answer that changes for its reason. The source's repository is private, so its
comments carry no author association: the replay gives them `OWNER` and
unedited. A read shorter than 40 hex, and a lens comment edited after posting,
read nothing here (54 recorded answers). The source's `full_sha`, which matched
a short read to the pull request's commits, is gone.
125 changes: 125 additions & 0 deletions fork-ci/actions/pr-queue/config.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
"""The merge queue's project facts: one JSON file in the project's repository (README.md, "Config").

Strict on purpose: an unknown key (a typo such as `required_check`), a key written twice, a missing required key, an
empty `required_checks` or a value of the wrong type is an error, and the queue then touches no PR. A queue that read a
wrong list of required checks would update, wait for or pass over the wrong PRs, so there are no guessed defaults for
anything a project must decide; only timings have defaults.
"""
import json
from dataclasses import dataclass

MERGE_METHODS = ('merge', 'squash', 'rebase')
# GitHub's CommentAuthorAssociation values a stranger cannot get: the repository's owner, a member of its organisation,
# an invited collaborator. Not CONTRIBUTOR, FIRST_TIME_CONTRIBUTOR, FIRST_TIMER or NONE, which anyone gets by commenting
# or by having a commit merged. MEMBER and COLLABORATOR say nothing about the permission (an organisation member may
# only read the repository): a project lists only the associations whose holders may all vouch for a head.
ASSOCIATIONS = ('OWNER', 'MEMBER', 'COLLABORATOR')


class ConfigError(Exception):
pass


@dataclass(frozen=True)
class Config:
required_checks: frozenset
merge_method: str
delete_branch: bool
bot_logins: tuple
lens_author_associations: tuple
override_prefix: str
override_association: str
ready_command: str
push_command: str
lens_format_doc: str
head_check: str
wait_seconds: int = 60
poll_seconds: int = 5
list_limit: int = 50

def ready(self, n):
"""The command that re-arms PR n after a lens read, as the project writes it."""
return self.ready_command.replace('{pr}', str(n))


def _text(v):
return isinstance(v, str) and v.strip() == v and v != '' and '\n' not in v


def _associations(v):
return isinstance(v, list) and v != [] and all(a in ASSOCIATIONS for a in v) and len(set(v)) == len(v)


def _no_duplicates(pairs):
"""json.loads keeps the last of a key written twice (say a merge-conflict fix left two `required_checks`): refuse."""
keys = [k for k, _ in pairs]
twice = sorted({k for k in keys if keys.count(k) > 1})
if twice:
raise ConfigError(f'key written twice: {", ".join(twice)}')
return dict(pairs)


def _int(lo, hi):
return lambda v: isinstance(v, int) and not isinstance(v, bool) and lo <= v <= hi


# key: (required, check, what a valid value is)
KEYS = {
'required_checks': (True, lambda v: isinstance(v, list) and v != [] and all(map(_text, v)) and len(set(v)) == len(v),
'a non-empty list of distinct check names (exactly the branch ruleset\'s required checks)'),
'merge_method': (True, lambda v: v in MERGE_METHODS, f'one of {", ".join(MERGE_METHODS)}'),
'delete_branch': (True, lambda v: isinstance(v, bool), 'true or false'),
'bot_logins': (True, lambda v: isinstance(v, list) and all(map(_text, v)),
'a list of logins whose comments never count as a lens (may be empty; `*[bot]` always counts as a bot)'),
'lens_author_associations': (True, _associations, f'a non-empty list of distinct author associations from '
f'{", ".join(ASSOCIATIONS)}: only their comments count as lens comments'),
'override': (True, lambda v: isinstance(v, dict) and set(v) == {'prefix', 'author_association'}
and _text(v['prefix']) and v['author_association'] in ASSOCIATIONS,
f'{{"prefix": "<text before the sha>", "author_association": one of {", ".join(ASSOCIATIONS)}}}'),
'ready_command': (True, lambda v: _text(v) and '{pr}' in v, 'the re-arm command with {pr} for the PR number'),
'push_command': (True, _text, 'the command that pushes a fixed branch'),
'lens_format_doc': (True, _text, 'where the project documents its lens comments'),
'head_check': (True, _text, 'the required check that fails a head no lens read (without one, a push to an armed '
'PR that is already up to date merges unread)'),
'wait_seconds': (False, _int(5, 600), 'whole seconds, 5-600'),
'poll_seconds': (False, _int(1, 60), 'whole seconds, 1-60'),
'list_limit': (False, _int(1, 100), 'how many open PRs the queue reads, 1-100'),
}


def parse(text, where='config'):
"""A Config from the JSON text, or ConfigError naming every problem at once."""
try:
raw = json.loads(text, object_pairs_hook=_no_duplicates)
except ConfigError as e:
raise ConfigError(f'{where}: {e}') from None
except ValueError as e:
raise ConfigError(f'{where}: not JSON: {e}') from None
if not isinstance(raw, dict):
raise ConfigError(f'{where}: must be a JSON object')
problems = [f'unknown key {k!r} (known: {", ".join(KEYS)})' for k in raw if k not in KEYS]
for key, (required, ok, what) in KEYS.items():
if key not in raw:
if required:
problems.append(f'{key} is missing: {what}')
elif not ok(raw[key]):
problems.append(f'{key} is {json.dumps(raw[key])[:80]}: must be {what}')
if not problems and raw['head_check'] not in raw['required_checks']:
problems.append(f'head_check {raw["head_check"]!r} is not one of required_checks')
if not problems and raw.get('poll_seconds', 5) > raw.get('wait_seconds', 60):
problems.append('poll_seconds is longer than wait_seconds')
if problems:
raise ConfigError(f'{where}: ' + '; '.join(problems))
override = raw.pop('override')
return Config(required_checks=frozenset(raw.pop('required_checks')), bot_logins=tuple(raw.pop('bot_logins')),
lens_author_associations=tuple(raw.pop('lens_author_associations')),
override_prefix=override['prefix'], override_association=override['author_association'], **raw)


def load(path):
try:
with open(path, encoding='utf-8') as f:
text = f.read()
except OSError as e:
raise ConfigError(f'{path}: cannot read it: {e}') from None
return parse(text, path)
Loading
Loading