Review drafts

An agent drafts a review of someone else's pull request on a public tracker issue; the operator approves it there; agent-board review send posts it as the bot. The design is tracker#848. This page describes what agent-board implements; the drafting brief and the caller's review-send.yml live in tracker.

Configuration

review send --config reads the caller's agent-board.json from its default branch: operator approves, bot drafts and sends (and must differ from the operator, or a draft could approve itself), and a review section, without which the command refuses to run:

{
  "operator": "example-operator",
  "bot": "example-bot",
  "review": {
    "targets": ["ostreedev/*", "containers/bootc"],
    "checkbox": "Send the newest draft as example-bot"
  }
}

targets lists the repositories a review may go to, as OWNER/* or OWNER/REPO. checkbox is the text of the body's task-list item.

The draft

An issue labelled review-draft holds drafts in its body or in comments by the bot or the operator. The newest is the last such block in the thread, the body first; one edited by anyone else is refused. Its header names the pull request, the head its lines refer to and the review event:

```review-draft
pr = "ostreedev/ostree#3649"
head = "a0207f11818b46729249315399c87fe99d5e3f21"
event = "REQUEST_CHANGES"   # COMMENT, REQUEST_CHANGES or APPROVE
```

## Review

The review body.

## Comments

### `src/libostree/ostree-sysroot-deploy.c:3415`

An inline comment, on the new side of the diff.

Approval

The operator approves the newest draft after its last edit, in one of two ways:

• a comment of theirs that is just /send, so that a quoted or example /send never approves;
• ticking - [ ] <checkbox> in the body, its only line that is the checkbox, outside fenced code, HTML blocks and HTML comments (a second such line, an example, leaves it unticked): --approved-by-edit EVENT takes the issues: edited payload of that edit ($GITHUB_EVENT_PATH), which must be the operator's and take the box from unchecked to checked. The send is bound to that edit, however late its job runs: the body must still be exactly the one it left, last edited by the operator, and the draft's last edit must come before the event's updated_at. A later draft, or any later edit of the body, even the operator's own, needs the box unticked and ticked again.

Either must also come after the bot's last refusal: a refusal revokes every approval before it. Without an approval nothing is written.

Sending

review send ISSUE prints the requests it would make; --apply, with the bot's token, makes them. It refuses a draft whose pull request is outside targets, closed, moved to another repository, or has a head other than the draft's, and a comment on a line not in the diff at that head. With --apply, a refusal comments the reason, in a comment whose first line is <!-- agent-board-review-refused -->.

Otherwise it claims the issue with a comment whose first line is <!-- agent-board-review-sent -->, checks the pull request is still open at head (else the claim becomes the refusal), posts one review at head whose body starts with a line saying the operator approved sending it, records the review's URL in the claim and closes the issue as completed. An issue with a claim is never sent again, even after a failure, which needs the operator to look before removing the claim.

The bot never rewrites the issue's body, its box included: GitHub has no conditional issue update, so a rewrite could overwrite an edit made while it ran. A box left ticked after a refusal or a send approves nothing more.