Pull Requestを作るたびに何を書けばいいか迷ったり、確認方法を書き忘れてレビューで聞き返されたりすることはありませんか。
GitHubのPull Request（プルリクエスト）テンプレートを使えば、作成画面の本文欄に共通の項目を自動で表示できます。
設定といっても、.github/pull_request_template.mdというファイルを1つ置くだけ。まずは単一のテンプレートを小さく作り、使いながら育てていくのが続けやすい方法です。
Pull Requestテンプレートは本文の書き忘れを減らすひな形
変更内容や確認方法を毎回ゼロから書いていると、どうしても抜けが出ます。
書く人によって説明の詳しさもばらつくので、レビューする側が「これはどう確認したの？」と質問するところから始まることも珍しくありません。
Pull Requestテンプレートは、こうした本文の書き出しをそろえるためのひな形です。
リポジトリにテンプレートファイルを追加しておくと、新しくPull Requestを作るとき、その内容が本文欄へ自動で入ります。
たとえば次のような項目を、最初から用意しておけるわけです。
- 何を変更したか
- なぜ変更したか
- どのように確認したか
- 関連するIssueはあるか
- レビューで特に見てほしい点はどこか
とはいえ、長い報告書を書かせるための仕組みではありません。レビューを始めるのに必要な情報を、書き忘れずに渡せる状態をつくる。テンプレートの役割はそこにあります。
初めは単一テンプレートで十分
個人開発や、Pull Requestの種類がまだ少ないチームなら、テンプレートは1つから始めるのがおすすめです。単一テンプレートは、次の3か所のどこかに置けば使えます。
| 置き場所 | ファイルのパス |
|---|---|
| リポジトリ直下 | pull_request_template.md |
docsディレクトリ | docs/pull_request_template.md |
隠しディレクトリの.github | .github/pull_request_template.md |
どこに置いても動きますが、リポジトリ直下のファイルを増やしたくないなら.github/にまとめると整理しやすいでしょう。
この記事でも.github/pull_request_template.mdを例に進めます。
もうひとつ大事なのが、テンプレートがほかの共同作業者にも使われるようになるのは、リポジトリのdefault branchへマージされてからだという点です。
default branchは多くの場合mainですね。作業ブランチにファイルを置いただけでは、まだ有効になっていません。
単一のPull Requestテンプレートを作る手順
作業の流れは、ファイルを作る、項目を書く、default branchへ取り込む、表示を確かめる、の4段階です。GitHubのWeb画面だけでも完結するので、ローカルの開発環境がなくても進められます。
1. テンプレートファイルを作る
対象のリポジトリで、次のファイルを新しく作ります。
.github/pull_request_template.mdWeb画面なら、ファイル一覧の上にある「Add file」から「Create new file」を選び、ファイル名の欄にこのパスをそのまま入力しましょう。
スラッシュを含めて入力すると、.githubフォルダーも一緒に作られます。ローカルで編集する場合も、同じ場所にMarkdownファイルを作ってコミットすれば同じ結果になります。
ファイル名や階層は、独自に変えないのがポイントです。
あとで紹介する複数テンプレート用のPULL_REQUEST_TEMPLATEディレクトリは別の仕組みなので、単一テンプレートのファイルと混同しないようにしてください。
2. Pull Requestで確認したい項目を書く
ファイルの中身は、Pull Requestの本文に最初から入れておきたい文章そのものです。
入れる内容の例としては、関連Issueへの参照、変更内容の説明、レビュー担当者へのメンションなどが挙げられます。
あとはリポジトリの作業の流れに合わせて選べば大丈夫。どのPull Requestでも答えられる質問を優先し、特定の変更でしか使わない欄は増やしすぎない方が、書く側の負担が軽くなります。
チェックボックスを置く場合は、「テストした」の一語で済ませず、何を確認したかが分かる書き方にするのがおすすめです。
自動テストのない小さなリポジトリなら、確認した環境や操作を書ける欄があると役立つでしょう。
3. default branchへ取り込む
ファイルをコミットしたら、Pull Requestを作ってdefault branchへマージしましょう。テンプレートの追加自体もPull Requestにしておけば、中身を確認してから取り込めるので安心です。
Web画面でdefault branchのまま作業していた場合は、コミットするときに新しいブランチを作る側を選び、そこからPull Requestを作成する流れになります。
4. テスト用ブランチから表示を確かめる
取り込みが済んだら、小さなテスト用ブランチを作ってPull Requestの作成画面を開いてみてください。本文欄にテンプレートの内容が入っていれば、設定は完了です。
表示されないときは、次の順で見直すと原因を切り分けやすくなります。
- テンプレートがdefault branchに入っているか
- ファイル名と置き場所が対応する形になっているか
- 単一用のファイルと複数用のディレクトリを混同していないか
- どのブランチ同士でPull Requestを作ろうとしているか
設定ファイルを増やして試す前に、今あるファイルのパスとdefault branchの状態を確かめる方が近道です。
初心者向けのテンプレート例
初版は、これくらいの短い内容から始められます。
## 変更内容
<!-- 何を変更したか、要点を書いてください -->
## 変更理由
<!-- なぜこの変更が必要かを書いてください -->
## 確認方法
<!-- 実行したテストや手動で確認した手順を書いてください -->
## 関連Issue
<!-- Closes #123 のように書きます。なければ「なし」と記入 -->
## レビュー時に見てほしい点
<!-- 判断に迷った点や、重点的に確認してほしい箇所を書いてください -->コメント記法で囲んだ案内文はHTMLのコメントとして扱われるので、作成後のPull Requestの表示には出てきません。ただ、本文の原文には残るため、実際の作成画面とプレビューで一度見え方を確かめておきましょう。
項目名は、リポジトリで普段使っている言葉に合わせると書きやすくなります。
文章や設定ファイルの変更が中心なら、「確認方法」より「確認したページ」や「変更前後の表示」の方が答えやすいかもしれません。
アプリ開発なら、テスト結果や画面の差分、データ変更の有無が必要になることもあります。
大事なのは、立派なテンプレートに見せることではなく、レビューの前に必要な情報がそろうことです。
空欄のまま出されがちな項目は削り、毎回コメントで追記をお願いしている情報は、新しい欄の候補にしてみてください。
複数テンプレートは変更の種類がはっきりしてから
機能追加、バグ修正、ドキュメント更新などで確認したい項目が大きく違うなら、テンプレートを複数用意できます。
置き場所はPULL_REQUEST_TEMPLATEというサブディレクトリで、リポジトリ直下・docs/・.github/のどこに作っても構いません。
.github/に置く場合は、次のような構成になります。
.github/
└── PULL_REQUEST_TEMPLATE/
├── feature.md
├── bug-fix.md
└── documentation.md使うときは、ブランチを比較するURLにtemplateというクエリパラメータを付けて、読み込むファイル名を指定します。
https://github.com/OWNER/REPOSITORY/compare/main...BRANCH?quick_pull=1&template=bug-fix.mdOWNERとREPOSITORY、比較するブランチ名、テンプレート名は、自分のリポジトリに合わせて書き換えてください。
quick_pull=1は、Pull Requestの作成画面を直接開くための指定です。
複数テンプレートはURLで指定して読み込む仕組みなので、用途ごとのURLをREADMEや開発の手引きにまとめておくと迷いません。
種類がはっきりしないうちに増やすと、かえってどれを使うか迷う原因になります。単一テンプレートで足りない場面が見えてから分けても、遅くはないです。
運用前に知っておきたい注意点
テンプレートのつまずきは、置いた直後よりも使い続けるうちに表れやすいものです。よくあるのは、テンプレートに頼りすぎることと、項目が増えて形だけになること。
あわせて、Issue templateとの役割分担と機密情報の扱いも決めておくと安心です。
テンプレートだけでは記入やレビューを強制できない
本文に項目が表示されても、作成者が消したり、空欄のまま出したりすることはできてしまいます。
テンプレートはあくまで記入を助ける仕組みです。承認数やステータスチェックをマージの条件にしたいなら、Rulesetsやブランチ保護を別に設定しましょう。
チェックボックスに印が付いていることも、品質の保証にはなりません。レビューでは、変更の差分や実際のテスト結果を見るのが基本です。
項目を増やしすぎない
長すぎるテンプレートは、どのPull Requestでも「該当なし」が並びがちです。毎回必ずほしい情報と、変更内容によって必要になる情報は分けて考えてください。
見直しのタイミングも、月1回のように決め打ちするより、レビューで不足や無駄に気づいたときで十分。テンプレートを更新するPull Requestに変更理由を残しておけば、項目が増減した経緯を後から追えます。
Issue templateと混同しない
Issue templateとPull Requestテンプレートは、使う場面も置き場所も違います。
Issueは不具合報告や要望など、作業を始める前の情報を整理するためのもの。Pull Requestは、実際の変更をレビューへ渡す場面で使います。
同じ質問を両方に置く必要はありません。Issueには背景と要件、Pull Requestには実装内容と確認結果というように役割を分けると、どちらのテンプレートも短く保てます。
機密情報を書かせない
「ログを貼る」「設定を貼る」とだけ書いた欄は、トークンや個人情報、顧客情報が紛れ込むきっかけになりがちです。必要なら「秘密情報を除いて貼る」のひと言を添えておきましょう。公開リポジトリでは特に、本文と添付ファイルを投稿前に見直すようにしてください。
向いている運用と別の仕組みを使う場面
Pull Requestテンプレートが力を発揮するのは、次のような場面です。
- 変更理由や確認方法の書き忘れを減らしたい
- 個人開発でも、後から変更の判断を振り返れるようにしたい
- 小規模チームで、レビュー前の情報をそろえたい
- 関連IssueとPull Requestを結び付けたい
- レビューのたびに同じ質問をしている
一方で、次のような目的はテンプレートの守備範囲の外です。それぞれに合った機能と組み合わせましょう。
| やりたいこと | 使う仕組み |
|---|---|
| mainへの直接変更を制限する | Rulesets、ブランチ保護 |
| テストを自動で実行する | GitHub ActionsなどのCI |
| 作業前の要望や不具合報告をそろえる | Issue template |
| ファイルごとにレビュー担当を決める | CODEOWNERS |
まずは「Pull Requestを読んだ人が、変更の目的と確認状況を理解できるか」を基準に本文欄を整え、必ず守らせたいルールだけを別の機能で適用する。
この順番で考えると、それぞれの仕組みの役割が混ざらずに済みます。
まとめ
GitHubのPull Requestテンプレートは、pull_request_template.mdをリポジトリ直下・docs/・.github/のどこかに置き、default branchへ取り込めば使えます。
本文欄に共通の項目が自動で入るので、書き忘れやレビュー前の聞き返しを減らせるのが一番のメリットです。
最初から項目や種類を増やす必要はありません。「変更内容」「変更理由」「確認方法」「関連Issue」など、レビューを始めるのに必要な項目だけで十分です。何件か使ってみて、毎回足りない情報を足し、使われない欄を削っていきましょう。
変更の種類ごとに聞きたいことがはっきり分かれてきたら、PULL_REQUEST_TEMPLATEディレクトリとtemplateクエリパラメータによる複数テンプレートを検討するタイミングです。
まずは作業ブランチに単一テンプレートを1つ追加してdefault branchへマージし、テスト用のPull Requestで表示を確かめるところから始めてみてください。
