📝

GitHub Pull Request のタスクリストがすべて完了している事を Task list completed で強制する

2022/06/12に公開約3,000字

まとめ

  • Task list completed を使うと GitHub Pull Request のタスクリストがすべて完了しないとマージできないように設定可能
  • インストール・設定はとてもかんたん

タスクリストとは?

ここでは GitHub のタスクリストを指します。日本語ドキュメントからタスクリストの説明を一部引用します。

タスクリストはタスクの集合で、それぞれのタスクはクリックできるチェックボックス付きの行に個別に表示されます。 タスクが完了しているか未完了かをマークするために、チェックボックスを選択あるいは選択解除できます。
タスクリストについて - GitHub Docs より

例えば Pull Request の本文で次の記述をすると、それぞれが1つのタスクになります。

- [x] 機能A の実装
- [x] 機能B の実装
- [ ] QA の確認

表示は次のようになります。

タスクリストの利用ケースとして、例えば次があります。

  • ある程度規模の大きな実装に入る前に、必要なタスクに分解・リストアップして、各タスクが完了したらチェックを入れ、すべてチェックされたら晴れてマージする
  • 機能開発者、レビューアそれぞれの実施項目をリストアップして、それぞれが出来ていればチェックを入れ、すべてチェックされたら晴れてマージする

モチベーション

先ほどの利用ケースの、「すべてチェックされたら」の部分は GitHub の標準設定で強制できません[1]

そこで GitHub apps の Task list completed を使うと、タスクリストがすべてチェックされていないとマージできないようにする事が可能です。

導入

まずはマーケットプレイスの Task list completed · GitHub Marketplace にアクセスし、インストールします。

利用は無料ですが、支払い方法の入力が必要です。導入したいリポジトリを選択できます(すべて or 個別)。

次に、導入したいリポジトリの Settings - Branches - Branch protection rules で、導入したいブランチのルールを新規作成します(すでに存在する場合は編集)。

Require status checks to pass before merging にチェックを入れると検索ボックスが表示されるので、task-list-completed を指定します。

インストール直後はここで検索ボックスが表示されない、もしくはヒットしない事もあるようです。その場合、次を試してください。

  1. Pull Request を作成する
  2. しばらく待つ(数時間〜)

最後に変更を反映します。

以上で、対象のブランチへの Pull Request でタスクリストを作成すると、次のように
タスクリストのチェックが行われます。

まだ完了していないタスクがあるため、マージがブロックされています。

すべてチェックすると次のようにマージ可能になります。

リスク

一応リスクについても記載しておきます。apps のインストール時に次の権限を許可する必要があります。

  • issues, metadata, and pull requests に対する読み取り
  • checks に対する読み取り書き込み

開発ルールによっては、このリスクが取れないケースもあると思います。幸い OSS[2] なので、公開されているソースコードを参考にして同等の機能を実装する方法もあります。

https://github.com/stilliard/github-task-list-completed

最後に

Task list completed はこれまで2年以上使っていて、大きな問題になった事はありません。

ごくまれに、全てチェックしてもパスしないケースがありましたが、Pull Request の本文を一度空にして保存すると実行されました[3]

最近、ネストされたタスクリストがカウントされない事に気づいたので Pull Request を出したところ、すぐにマージしていただき、リリースまで行われました。

https://github.com/stilliard/github-task-list-completed/pull/27

たまたま作者の都合にタイミング良く合っただけかもしれませんが、とても体験が良かったです。また、セキュリティの対応も行われていて、継続的にメンテナンスされている印象です。

脚注
  1. 執筆時点では ↩︎

  2. ライセンスは MIT LICENSE ↩︎

  3. 空にして実行された事を確認した後、再度前の内容に戻すと期待した実行が行われる ↩︎

Discussion

ログインするとコメントできます