Pointsman でプルリクエストをレビューする

Pointsman は、プルリクエストに次に何が必要かを判定できます。軽いレビュー、人の確認、修正、承認のどれかです。GitHub のコネクターは新しいコミットごとにプロファイルに判定を依頼し、その結果をプルリクエストに表示します。このガイドでは、デプロイを「表示するだけ」から「承認する」まで、1 段階ずつ進めます。

Pointsman のデプロイ(Pointsman をデプロイする)にモジュール @pointsman/github を入れ、GitHub のコネクターを 2 つの GitHub アプリとともに設定しておく必要があります(GitHub コネクター)。

1. シャドーモードで始める

既定では、コネクターは判定をチェックとして書くだけで、その結論は neutral です。マージを止めることはありません。しばらくこのまま動かし、コネクターの判定と人の判断を比べます。チェックには、どのアクションを取るはずだったかと、その理由が表示されます。

2. プロファイルを選ぶ

コネクターは、GITHUB_CONNECTOR に並べたプロファイルに判定を頼みます。最初は例のプロファイルから始めます(開発ワークフローの例、英語)。

• pr-docs-check: プルリクエストが変えるのはドキュメントだけで、軽いレビューで足りるか。
• workflow-check: プルリクエストが変える GitHub Actions のファイルを、安全にマージできるか。

自分たちのプロファイルは、設定用リポジトリに置きます。ルールでは、変更されたファイル、チェックの結果、誰が push したかといった GitHub のファクトを読みます(ファクトの型)。

3. アクションを有効にする

GITHUB_CONNECTOR で、プロファイルの判定のアクションをコネクターの動作に対応づけます。対応づけていないアクションは、チェックとして表示されるだけです。この例では、アクション light でラベルを付けます。

{
  "repos": ["owner/name"],
  "profiles": ["pr-docs-check"],
  "actions": {
    "pr-docs-check": {
      "light": { "do": "label", "labels": ["docs-only"] }
    }
  }
}

コネクターは、コメント、ラベルの追加、レビューの依頼、承認、承認の維持ができます。どれもコミットごとに 1 回だけで、人が判定を確認している間は何もしません(アクション)。そのため、人が先に確認するアクション(既定では review)には動作を対応づけないでください。確認が終わるまで何も起きません。

4. Pointsman に承認させる

アクションを approve に対応づけるのは、プロファイルのルールがそれを支えられるときだけにします。

• 権限。 アプリの承認が必要な承認数に数えられるのは、コネクターのアプリに Contents と Pull requests の読み書きの権限があるときだけです(2 つのアプリ)。権限がなければ、承認は表示されても数えられません。コネクターのチェックの結論は常に neutral なので、必須のチェックにしても承認の代わりにはなりません。
• 古い承認を取り消す。 ブランチのルールセット(GitHub のブランチ保護の設定)で「Dismiss stale pull request approvals when new commits are pushed」を有効にします。コネクターも自分の古い承認を取り消しますが、それは次に動いたときです。
• コードオーナー。 アプリはコードオーナーになれません。CODEOWNERS(どのファイルを誰がレビューするかを定めるファイル)が変更されたファイルを含み、ルールセットがコードオーナーのレビューを求める場合は、人の承認がやはり必要です。
• フォークからのプルリクエストは承認しません。
• 承認を残す条件。 同じコミットへの後の判定は、approve か keep_approval に対応づけたアクションでない限り、承認を取り消します。ファクト github_app_approval と keep_approval を使うと、たとえば承認のあとに AI のレビューサービスがレビューしても、承認が取り消されません(承認が残る条件)。

5. リリースと依存関係のプルリクエストをファクトだけで承認する

AI の回答をまったく必要としないプルリクエストもあります。

• バージョンの欄を動かし、変更履歴に追記するだけのリリースのプルリクエスト(github_release)。
• npm の開発用の依存関係をパッチの範囲で上げるだけの Dependabot のプルリクエスト(github_bump。patch と数えるのはバージョン 1.0.0 以降だけで、0.x のパッチの更新は minor と数えます)。

どちらのファクトも、誰が変更したかは示しません。そのため、github_pr(作成者、署名、誰が push したか)と組み合わせます。依存関係のケースを増やすには、Dependabot の開発用のパッチ更新を、それだけのプルリクエストにまとめます。依存関係は最初に当てはまるグループに入るので、このグループを先に書きます。残りの minor と patch の更新は 2 つ目のプルリクエストに入り、通常のレビューを受けます。major の更新は、それぞれ別のプルリクエストになります。

.github/dependabot.yml

version: 2
updates:
  - package-ecosystem: npm
    directory: /
    schedule:
      interval: weekly
    groups:
      npm-dev-patch:
        dependency-type: development
        update-types: [patch]
      npm:
        update-types: [minor, patch]

AI のレビューサービスもこれらのプルリクエストをレビューすると、そのレビューによってプロファイルが読む内容が変わります。サービスにはスキップさせます。CodeRabbit の場合は、リリースのプルリクエストのタイトルを Release 0. で始め、リポジトリの .coderabbit.yaml でそのタイトルを無視させます(キーワードはタイトルのどこにあっても一致するため、Release だけにはしません。バージョン 1.0 からは Release 1. にします)。この設定は、リリースのプルリクエストだけでなく、タイトルにキーワードを含むすべてのプルリクエストをスキップします。作成者がほかのタイトルにキーワードを入れて、AI のレビューを避けることもできます。判定はプロファイルのルールが行うため変わりませんが、そのプルリクエストでは AI のレビューがなくなります。設定は次のとおりです。

reviews:
  auto_review:
    ignore_title_keywords: ["Release 0."]

次に読むページ

• GitHub コネクター: すべてのアクション、設定、制限。
• ファクトの型: GitHub のファクトのすべてのフィールド。
• 判定のしくみ: AI の回答だけでプルリクエストが通ることがない理由。