---
title: "要約コメントと Approve"
description: "レビュー指摘の要約を GitHub の PR にコメント 1 本で出し、マージ可になったらレビュワー本人の名義で Approve し、未解決の High / Medium があれば指摘を出した本人の名義で変更要求を出す"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.koyori.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 要約コメントと Approve

## 概要

[レビュー指摘](https://docs.koyori.app/dev/features/review-findings)の結果を GitHub の PR へ出す部分を書く。PR に置くのは bot の要約コメント 1 本と、マージ可になったときのレビュワー本人の Approve、未解決の High / Medium があるときの指摘を出した本人の変更要求だけである。どちらも apalis のジョブが非同期に行い、失敗しても起票や状態遷移を巻き戻さない。判断の理由は親ページの[決定の記録](https://docs.koyori.app/dev/features/review-findings#決定の記録)の節に書く。

## 振る舞い

### 投稿先

- 投稿主体は GitHub App で、既存連携の installation token を使う。個人の PAT に依存しない
- 投稿先はラウンドに保存したリポジトリ（`repo_owner` / `repo_name`）である。保存したリポジトリが現在の連携先と違う、または連携が無いラウンドは投稿しない
- 集計の範囲・合流の鍵・投稿先・installation token は、連携行を 1 回だけ引いてそこから作る
- GitHub 連携の無いプロジェクトと、GitHub App が未設定のサーバーでは投稿をスキップする。起票・管理はできる
- 現在の連携先で出したラウンドが 1 件も無い PR にも書かない
- 投稿・編集の失敗はベストエフォートで、ログに残すが API は成功させる
- PR メタの取得に失敗しても要約は投稿する。PR 番号だけで足りる

### コメントの特定

コメントは 1 PR × 1 プロジェクトに 1 本である。HTML マーカーにプロジェクト ID を含める（例は `<!-- koyori-review-summary:{project_id} -->`）。同じリポジトリを複数プロジェクトが見られるので、合流とロックの鍵も project を含めて単位を揃える。

- 探索時は「マーカー一致」かつ「作成者が自分（この GitHub App の bot）」の両方を必須にする。第三者の同一マーカーは無視して新規作成する
- 一度投稿できたら `comment_id` を保存し、以後は探索せずに直接更新する。探索は初回と、保存した値を失ったときの復旧手段である
- 保存した値を捨ててよいのは、編集が 404（コメントが存在しない）を返したときだけである。権限エラー・レート制限・5xx・通信断では値を保持し、次回の更新に任せる
- マーカー探索は先頭 5 ページ（100 件 × 5）までである。要約は初回に作られるので実際には 1 ページ目で見つかる。見つからなければ新規投稿になり、次回以降はその新しい方が更新され続ける

### 内容

ラウンド数（R1, R2, …）と最新ラウンドの総評、重大度 × 状態の件数表、マージ可否、オーナー代行での棄却件数（あれば）、task の指摘一覧へのリンク、最終更新時刻を載せる。リンクの URL は既存の `email_verification_app_url`（アプリの公開 URL）を流用する。

引き継いだ指摘だけがあり、レビューのラウンドが 1 件も無い PR には「未レビュー」と書く。マージ可でも Approve でもない。写しのラウンドは、ラウンド数・最新ラウンドの `head_sha`・Approve の名義に数えない（[引き継ぎ](https://docs.koyori.app/dev/features/review-findings#引き継ぎ)）。塞ぐ指摘があるときは、ふだんどおり「マージ不可」と書く。

コメントは最終更新時刻の時点のスナップショットである。push だけでは更新されない。更新の契機は task 側のラウンド作成と状態遷移だけである。

### HEAD の鮮度

ジョブは PR メタ（既に取得している `GET /pulls/{number}` の応答）から現在の `head.sha` を読み、最新ラウンドの `head_sha` と比較する。

- 不一致なら「レビュー後に更新あり」としてマージ可を出さない
- PR メタが取れないときもマージ可を出さない。件数表は出す
- 取得した `head.sha` は確認時刻とセットでラウンドへキャッシュし（`pr_head_sha` / `pr_head_checked_at`。`pr_title` / `pr_author` と同じ流儀）、[画面](https://docs.koyori.app/dev/features/review-findings#画面)が使う

### Approve

マージ可になったら、最新ラウンドの作成者（レビュワー）本人の名義で PR を Approve する。本文は無い。条件は要約コメントが「マージ可」と書く条件と同一（`SummarySnapshot::merge_ready`）で、加えて PR が open であること。最新ラウンドの作成者にするのは、鮮度の照合と同じく「この commit を見た」と宣言した人と承認者を揃えるためである。

- トークンは GitHub App のユーザー認可（連携の provider `github_app`。[OAuth 認証](https://docs.koyori.app/dev/features/auth/oauth)）で得たものである。権限は「App の権限 ∩ 本人の権限」で、scope は無い。ログイン用の GitHub 連携（OAuth App、`read:user` / `user:email`）では承認できない
- レビュワーが連携していなければ承認しない。ログに残すだけである
- トークンは既定で 8 時間で切れる。期限が近ければ使う前にリフレッシュトークンで更新し、回転した新しいトークンを保存し直す
- 更新は連携の行をロックして直列にする。同じ利用者の更新が並ぶと、後の 1 本は先に無効になったリフレッシュトークンを使って失敗する
- 承認は `commit_id` に最新ラウンドの `head_sha` を明示して出す
- 同じ commit への本人の承認（`APPROVED`、または人に取り下げられた `DISMISSED`）が既にあれば出さない。ただし本人の最後の決定が task の取り消し（次節）なら承認し直す
- 本人は login ではなく GitHub アカウントの数値の ID で見る。改名に強い
- 既に承認があるかは DB に持たず、GitHub のレビュー一覧を判定の元にする
- レビュワーが PR 作者なら GitHub が 422 で拒み何も残らないので、PR の作者がレビュワー本人と同じ（GitHub アカウントの数値の ID で見る）ときは投稿を試みない。作者が分からないときは試みる
- 失敗（連携の取り消しで 401、リポジトリへの権限が無く 403 など）も含め、要約コメントと同じくベストエフォートでログに残すだけである
- push 後に残る古い承認は、branch protection の「Dismiss stale pull request approvals when new commits are pushed」で落とす

### 変更要求

head が新しく、High / Medium の未解決指摘があるとき、指摘を出した本人の名義で PR に変更要求（`REQUEST_CHANGES`）を出す。Approve と対になる操作で、画面・API・CLI に入口は無く、要約ジョブが自動で行う。

- 条件は PR が open で、最新ラウンドの `head_sha` が今の PR head と同じで、High / Medium の未解決（`open` / `fixing` / `fixed`）が 1 件以上あること。Approve の条件の裏返しで、`fixed`（確認待ち）は `verified` になるまで未解決に数える
- 出す人は、今の head にラウンドを出した人のうち、自分のラウンド（head を問わない）に High / Medium の未解決指摘がある人である。指摘を出していない人や、今の head を見ていない人には出さない。`github_app` の連携が無い人は飛ばす
- 本人の同じ commit への最後の決定（`APPROVED` / `CHANGES_REQUESTED` / `DISMISSED`。`COMMENTED` は無視する）が `APPROVED` なら、次節の承認の取り消しとして出す。決定が無いときは新しく出す
- 同じ commit に変更要求（目印の有無を問わない）か `DISMISSED` があれば出さない。前の head の変更要求が本人の最後の決定として残っているときも、GitHub 上は既に変更要求なので重ねて出さない。人の判断と争わず、ラウンドごとに同じレビューが増えるのも避ける
- 目印は承認の取り消しと共用する（`<!-- koyori-approval-revoked:{project_id} -->`）。承認し直しと再レビュー待ちは、承認の取り消しと同じく task が出した変更要求にも効く
- `commit_id` に最新ラウンドの `head_sha` を明示する。本文は「task に未解決の High / Medium の指摘があるため、変更を求めます」と、指摘一覧の URL（あれば）である
- プロジェクトごとの有効・無効の設定は無い。`github_app` の連携をしていない人には出ない
- 失敗は承認と同じくベストエフォートである。PR 作者がレビュワー本人のときは GitHub が 422 で拒むので、投稿を試みずに飛ばす（debug ログ）。422 は info、それ以外は warn でログに残し、ジョブは失敗にしない。要約コメントは先に更新済みである

### 承認の取り消し

承認した後に、同じ head へ High / Medium の未解決指摘を含むラウンドが出てマージ可でなくなったら、承認を取り消す。前節の変更要求と同じ操作で、レビュワー本人のトークンで `REQUEST_CHANGES` を出し、本人の承認を上書きする。dismiss は保護ブランチで管理者権限が要り、人の取り下げと区別もできないので使わない。

- 条件は PR が open で、最新ラウンドの `head_sha` が今の PR head と同じで、マージ可でないこと。head が違うときは何もしない。push 後の古い承認は branch protection に任せる
- 対象は、今の head に対するラウンドを出した全レビュワー（重複なし）である。承認したのが前のラウンドの作成者のこともあるので、最新ラウンドの作成者に限らない。自分のラウンドに未解決の指摘が無い人も、承認があれば取り消す。`github_app` の連携が無い人は飛ばす
- 各人の判断は、その人の同じ commit へのレビューのうち `APPROVED` / `CHANGES_REQUESTED` / `DISMISSED` の最後の 1 件で行う。`COMMENTED` は無視する。最後が `APPROVED` のときだけ取り消す。それ以外は前節の変更要求の規則で決める。人の判断と争わず、二重にも出さない
- `commit_id` に今の head を明示する。本文は人が読める説明と指摘一覧の URL（あれば）に、task が出したと分かる HTML コメントの目印を入れる。目印はプロジェクトごとである（`<!-- koyori-approval-revoked:{project_id} -->`）
- 承認し直す判断は、本人の最後の決定（commit を問わない）が目印付きの `CHANGES_REQUESTED`（task が出した変更要求と取り消し）かどうかで行う。前の head で出したものも照合する。GitHub は push で stale な承認を取り下げても、変更要求は取り下げないためである。人が取り下げた承認や、目印のない人の変更要求の後は承認し直さない
- マージ可に戻ったときは、最新ラウンドの作成者に加えて、今の head にラウンドを出した他のレビュワーのうち最後の決定が目印付きの `CHANGES_REQUESTED` の人も承認し直す。task が変更を求めた人の変更要求が残ると、保護ブランチでマージが止まり続けるためである。task が変更を求めていない人は承認しない
- 今の head にラウンドを出していない人は、task が変更を求めていても承認しない（その head を見ていない）。代わりに、指摘が片付いて head も新しくても、最後の決定が目印付きの `CHANGES_REQUESTED` の人が 1 人でも今の head にラウンドを出していなければマージ可にしない。要約コメントは「再レビュー待ち」として、その人の login を出す。承認も取り消しもしない。その人が今の head にマージ可のラウンドを出せば、本人の名義で今の head を承認し、変更要求を上書きする
- 再レビュー待ちの判定は、App のトークンで PR のレビュー一覧を読み、GitHub アカウントの数値の ID を `github_app` 連携の `provider_user_id` と突き合わせて行う。一覧の取得に失敗したときと上限で打ち切られたときは、待ちなしとして warn でログに残す
- レビュー一覧は 5 ページ（500 件）までしか辿らない。その先に最後の決定があるかもしれないので、打ち切られたときは取り消しも変更要求も出さず、warn でログに残す。承認側は従来どおり `APPROVED` / `DISMISSED` があれば出さず、目印による承認し直しもしない
- 失敗は承認と同じくベストエフォートである。422 は info、それ以外は warn でログに残し、ジョブは失敗にしない。要約コメントは先に更新済みである

### 更新の契機とジョブ

更新の契機はラウンドの作成時と指摘の状態遷移時で、apalis ジョブで非同期に行う。ペイロードに機微情報を載せない既存規約に従う。

ジョブは投入時に見ていたリポジトリをペイロードに持つ。リポジトリ名は機微情報ではないので載せてよい。更新待ちのフラグとロックの鍵は投入側がラウンドに保存したリポジトリで作る。実行時に連携先が変わっていたら、投入時のリポジトリのフラグだけを落として投稿せずに降りる。新しい連携先の分の更新は、そちらの遷移が積む。

### 合流

同一 (project, リポジトリ, pr) の更新要求は 1 本に合流させる。投入前に更新待ちのフラグを立て、既に立っていれば積まない。

- フラグを落とすのは、ロックを取れたジョブ、取れずに積み直すジョブ、投入時から連携先が変わっていて降りるジョブだけである。最初のものは最新状態を読む前に落とすので、合流された更新も次の 1 回に必ず含まれる
- フラグには TTL を置く。TTL が切れれば次の遷移で更新が再開する
- フラグの TTL は投入からジョブがそれを落とすまで（キューでの滞留とロック待ち）の最悪ケースより長く取る。ロックの TTL とは基準が違うので、同じ値を流用しない
- ロックを握ったまま死んだジョブがいる間は、フラグが切れて再投入されてもロックで弾かれるだけなので、フラグをロックの TTL より長くする必要はない

### 直列化

合流に加えて、同一 (project, リポジトリ, pr) のジョブ実行そのものを直列化する。

- ロックを取れなかったジョブは、フラグを落として少し後ろへ積み直し、自分は正常終了する。積み直した側が最新状態を読み直す
- 積み直しは回数で打ち切らない。持ち主が落ちてロックが TTL で失効するまで待つ
- 待ち時間はキューを見に行く刻みより長く取る
- ロックはランダムなトークンを値に置き、TTL 付きで取る。解放はそのトークンが現在値と一致するときだけ行う（`service::github::import_lock` と同じ形）
- TTL はワーカーが投稿中に落ちた場合の保険で、ジョブ 1 回分の GitHub API 往復（トークン取得・PR メタ・コメント探索・投稿）が最悪ケースで収まる長さにする

### 定数の現在値

| 定数 | 値 |
|---|---|
| 更新待ちのフラグの TTL | 5 分 |
| ロックの TTL | 10 分 |
| ジョブの再試行 | 3 回 |
| ロックが取れないときの積み直し | 5 秒後 |
| キューのポーリング | 2 秒間隔 |

## 未実装と既知の制限

- push で要約コメントを追従させない。webhook の push イベント処理が要り、受信基盤は既存（Issue の取り込みで使用中）である。別仕様で扱う
- 変更要求と取り消しの `REQUEST_CHANGES` は、レビュワー本人が GitHub 上で見ると変更要求として残る。解消されて承認し直すまで、保護ブランチでは必須レビューを満たさない
- 人が task の変更要求を取り下げた（dismiss）commit は、マージ可になっても承認しない。`DISMISSED` は承認の取り下げと区別できず、人の判断と争わないため
- PR 作者がレビュワーのときは GitHub が 422 で拒むので、Approve も変更要求も出さない。作者でない他のレビュワーには、その人の名義で出す
- 再レビュー待ちは要約コメント（と承認）にだけ反映する。集計 API の `gate` と CLI のマージ前ゲートは、GitHub を呼ばない方針（[マージ可否](https://docs.koyori.app/dev/features/review-findings#マージ可否)）なので反映しない。待ちの間も `ready` になりうる
- 複数レビュワーの承認が無い。承認するのは最新ラウンドの作成者だけで、同じ head に複数人がラウンドを出しても、それ以前の作成者は承認しない。必須承認が 2 名以上のリポジトリでは足りない

次の受け入れ条件はテストが無い。

- 保存した `comment_id` の寿命: 一時的な失敗（レート制限・5xx・通信断）のあと再実行しても要約コメントは 1 本のまま。対照として、コメントが手で削除されていれば（編集が 404）作り直す

次の受け入れ条件は、テストファイルへ移した部分を除いた次のサブ条件のテストが無い。

- 正常系: 状態遷移で同じコメントが更新される通し
- 要約コメント: 投稿失敗は起票を巻き戻さずログに残る
- 要約コメントの鮮度: PR メタの取得に失敗したときの実経路と、件数表が出ること
- 要約コメントの持ち主: 同じリポジトリへ 2 つのプロジェクトが連携している PR で互いを上書きしない通し
- マーカーの先取り: 新規に作成して以後はそれを更新すること
- 要約コメントの直列化: 少し後ろへ積み直す遅延
- 持ち主が消えたときの復帰: ジョブが再試行を使い切っても、フラグの TTL 経過後の状態遷移で更新が再開すること、ロックを実際に期限切れにする検証

Source: https://docs.koyori.app/dev/features/review-findings/github-comment/index.mdx
