GitHub - Pull Requests

概要

Pull Request (PR) は、あるブランチで行ったコード変更を別のブランチにマージするよう提案して、
チームメンバーによるレビューとディスカッションを経てリポジトリに統合するためのメカニズムである。

PRを活用することにより、コードの品質向上、知識の共有、バグの早期発見が可能となる。
変更内容は差分 (diff) として可視化され、レビュアーはコメントや提案を通じてフィードバックを提供できる。

PRページは、下表に示す4つのタブで構成される。

Pull Requestのタブ
タブ	説明
Conversation	コメント、レビュー、イベントのタイムライン
Commits	PRに含まれるコミットの一覧
Checks	CI/CDやステータスチェックの結果
Files changed	変更されたファイルの差分表示

開発モデル

GitHubでは、PRを活用する開発モデルとして主に2種類が存在する。

Pull Requestの主なコラボレーションモデル
モデル	説明
フォーク & PRモデル	オープンソースプロジェクトに適したモデル誰でもリポジトリをフォークして変更を加え、元のリポジトリへPRを送ることができる。貢献者にリポジトリへの直接プッシュ権限を与える必要がない。
共有リポジトリモデル	小規模チームや社内プロジェクトに適したモデルチームメンバーが同一リポジトリに対して直接プッシュ権限を持つ。フィーチャーブランチを作成してPRを送る運用が一般的である。

Pull Requestの作成

Web UIでの作成

GitHub Web UIからPRを作成する基本的な手順を以下に示す。

ブランチに変更をプッシュした後、リポジトリページに移動する。
表示される通知バナーの[Compare & pull request]ボタンを押下する。
baseブランチ (マージ先) と compareブランチ (変更元) を選択する。
タイトルと説明を記入する。
[Create Pull Request]ボタンを押下してPRを作成する。

baseブランチには変更のマージ先となるブランチ (例: main) を指定して、compareブランチには自身が作業したフィーチャーブランチを指定する。

ドラフトPull Request

ドラフトPRは、作業が進行中であることを示すための機能である。
レビューの準備が整っていない段階でも、進捗を共有したり早期にフィードバックを得たりする目的で使用できる。

ドラフトPRの特徴は以下の通りである。

マージボタンが無効化されており、誤ってマージされる心配がない。
レビュアーへのレビュー要求通知が自動送信されない。
作業内容を早期に共有して、方向性のフィードバックを受けることができる。

作成方法は、PR作成画面の[Create Pull Request]ボタン横のドロップダウンから[Create Draft Pull Request]を選択する。

レビュー準備が完了したら、[Conversation]タブ下部の[Mark as ready for review]ボタンを押下することで、通常のPRに昇格できる。

PRテンプレート

PRテンプレートを設定することで、PR作成時に説明欄へ定型文を自動挿入できる。
チームで統一したフォーマットのPR説明を記述するよう促すことができる。

テンプレートファイルの配置場所
.github/pull_request_template.md

テンプレートの記述例を以下に示す。

 ## 変更内容
 <!-- 変更の概要を記述してください -->
 
 ## 変更の理由
 <!-- なぜこの変更が必要か記述してください -->
 
 ## テスト方法
 <!-- 動作確認の手順を記述してください -->
 
 ## 関連Issue
 <!-- 関連するIssue番号を記述してください (例: closes #123) -->

PRの説明の書き方

効果的なPRの説明を書くことにより、レビュアーが変更内容を素早く理解できるようになる。

PRの説明に含めると良い項目を以下に示す。

変更の概要
何を変更したか、なぜ変更が必要だったかを簡潔に説明する。
変更の影響範囲
どのコンポーネントやファイルに影響するかを明記する。
テスト方法
レビュアーが動作確認できるよう、手順を記述する。
スクリーンショット
UIの変更がある場合は、変更前後のスクリーンショットを添付する。
関連Issue
関連するIssueやチケット番号を記載する。

コードレビュー

レビューの依頼

PRの右側パネルにある[Reviewers]セクションから、レビューを依頼するユーザまたはチームを選択できる。

GitHubは、git blameのデータを分析して、変更されたコードに関連する知識を持つ可能性が高い貢献者をレビュアー候補として自動提案する。

レビュー依頼を受けたユーザには通知が送信され、レビュー待ちの状態としてマークされる。

レビューコメント

レビュアーはPRに対して複数の種類のコメントを残すことができる。

一般コメント
[Conversation]タブのコメント欄から投稿する。

PR全体に対するフィードバックや質問に使用する。
行コメント
[Files changed]タブで特定のコード行にカーソルを合わせ、表示される[+]アイコンを選択して投稿する。

特定のコード箇所に対する具体的な指摘に使用する。
提案 (Suggestion)
行コメントの入力欄にある[Add a suggestion]ボタンを使用して記述する。

PR作成者が直接コードを修正・適用できる形式でコード変更を提案できる。

レビューステータス

レビュアーはフィードバックを送信する場合に、下表に示す3つのステータスのいずれかを選択する。

レビューステータス一覧
ステータス	説明	用途
Comment	フィードバックのみ	マージの承認も拒否もしない場合に使用する。質問や軽微な提案に適している。
Approve	マージ承認	変更内容に問題がなく、マージを承認する場合に使用する。
Request changes	修正要求	マージ前に修正が必要な問題がある場合に使用する。修正が完了するまでマージがブロックされる。

CODEOWNERSによる自動レビュー

CODEOWNERSファイルを設定することにより、特定のファイルやディレクトリの変更に対してレビュアーを自動的にアサインできる。

ファイルの配置場所
.github/CODEOWNERS

CODEOWNERSファイルの記述例を以下に示す。

# 全てのファイルのオーナーを設定する
* @global-owner1 @global-owner2

# JavaScriptファイルのオーナーを設定する
*.js @js-owner

# docsディレクトリのオーナーを設定する
/docs/ @docsteam

CODEOWNERSファイルの特徴と注意事項を以下に示す。

パターンマッチングは .gitignore と同様の構文を使用する。
ファイルサイズは、3[MB]未満に制限されている。
リポジトリの[Settings] - [Branches]から[Require code owner review]を有効化することにより、CODEOWNERSに指定されたオーナーのレビューを必須にできる。

Suggested Changesの適用

レビュアーが提案 (Suggestion) を送信した場合、PR作成者はコメント上のボタンから直接コードに変更を適用できる。

適用方法には以下の2種類がある。

個別適用
各Suggestionコメントの[Commit suggestion]ボタンを押下して、提案を1件ずつ適用する。
一括適用
各Suggestionコメントの[Add suggestion to batch]ボタンを押下して複数の提案をまとめ、後から一括でコミットする。

Suggested Changesを適用してコミットすると、提案を行ったレビュアーが自動的にそのコミットのco-author (共同著者) として追加される。

ステータスチェック

ステータスチェックとは

ステータスチェックは、PRがマージされる前に自動的に実行される検証プロセスである。
テストの実行、コードのリント、ビルドの成功確認等、コードの品質を担保するための条件を自動チェックできる。

ステータスチェックの結果はPRの[Conversation]タブに表示され、各チェックの成否を確認できる。

必須ステータスチェック

特定のステータスチェックが全てパスした場合のみマージを許可する設定が可能である。

設定手順を以下に示す。

リポジトリの[Settings]タブに移動する。
[Branches]セクションを選択する。
保護対象のブランチのルールを編集する。
[Require status checks to pass before merging]を有効化する。
必須とするチェック項目を選択する。

GitHub Actionsとの連携

GitHub Actionsを使用することにより、PRへのプッシュやPRのオープンをトリガーとしてCI/CDパイプラインを自動実行できる。

PRに対してステータスチェックを実行するワークフローの例を以下に示す。

 name: CI
 
 on:
   pull_request:
      branches: [ main ]
 
 jobs:
   test:
      runs-on: ubuntu-latest
      steps:
         - uses: actions/checkout@v4
         - name: Run tests
           run: npm test

上記のワークフローは、mainブランチへのPRが作成・更新されるたびに自動実行され、テスト結果がステータスチェックとしてPRに反映される。

マージ

マージコミット

デフォルトのマージ方式である。

PRブランチの全てのコミットをそのまま保持した上で、マージコミットを1つ追加してベースブランチに統合する。

git merge --no-ff feature-branch

全てのコミット履歴が保持される。
マージコミットによりブランチの分岐・合流が履歴上で明確に確認できる。
複雑なコミット履歴になる場合がある。

スカッシュマージ

PRブランチの複数のコミットを1つのコミットに圧縮してベースブランチに追加するマージ方式である。

コミット履歴がシンプルになる。
作業中の試行錯誤的なコミットを1つにまとめられる。
長期間運用するブランチを再利用する場合、マージ済みコミットのSHAが異なるため注意が必要である。

リベースマージ

PRブランチのコミットをベースブランチの先頭に順番に適用して、線形の履歴を作成するマージ方式である。

マージコミットが作成されず、線形の履歴が維持される。
各コミットには新しいSHAが付与される。
コンフリクトが発生している場合は使用できない。

自動マージ (Auto-merge)

必須ステータスチェックの完了およびレビュー承認の条件を満たした時点で、PRを自動的にマージする機能である。

有効化手順を以下に示す。

PRページの[Enable auto-merge]ボタンを押下する。
マージ方式 (マージコミット、スカッシュ、リベース) を選択する。
[Confirm auto-merge]を選択して確定する。

必須チェックが全てパスし、必要なレビュー承認が得られると自動的にマージが実行される。

マージキュー (Merge Queue)

複数のPRを順序立てて安全にマージするための機能である。

各PRを個別にマージするのではなく、キューに追加された順に自動でテストおよびマージを行う。

複数PRが同時にマージされることによるコンフリクトリスクを軽減できる。
マージキューはブランチ保護設定から有効化できる。
キューに追加されたPRは、前のPRの内容を含んだ状態でテストが実行される。

マージ後の処理

マージ完了後、PRのソースブランチ (head branch) を自動的に削除する設定が可能である。

設定手順を以下に示す。

リポジトリの[Settings]タブに移動する。
[General]セクションの[Pull Requests]項目を確認する。
[Automatically delete head branches]を有効化する。

誤って削除した場合でも、PRページの[Restore branch]ボタンからブランチを復元できる。

コンフリクトの解決

コンフリクトは、PRのソースブランチとベースブランチの両方で同一ファイルの同一箇所が変更された場合に発生する。

マージ前にコンフリクトを解決する必要がある。

Web UIでの解決

行レベルの単純なコンフリクトはGitHub Web UIで解決できる。

PRページで[Resolve conflicts]ボタンを押下する。
コンフリクトが発生しているファイルが表示される。
コンフリクトマーカー (<<<<<<<, =======, >>>>>>>) を含む箇所を編集して、残すべき変更内容に修正する。
[Mark as resolved]を選択する。
全てのファイルのコンフリクトを解決したら[Commit merge]を選択する。

複雑なコンフリクト (バイナリファイルや大規模な変更) はWeb UIでは解決できないため、コマンドを使用する。

コマンドラインでの解決

コマンドを使用したコンフリクト解決の手順を以下に示す。

# 1. ベースブランチをチェックアウトして最新の状態に更新する
git checkout main
git pull origin main

# 2. PRのソースブランチをチェックアウトする
git checkout feature-branch

# 3. ベースブランチをマージしてコンフリクトを発生させる
git merge main

# 4. コンフリクトが発生したファイルを手動で編集して解決する
# (エディタでコンフリクトマーカーを削除して修正する)

# 5. 解決済みファイルをステージングする
git add .

# 6. マージコミットを作成する
git commit

# 7. リモートにプッシュする
git push origin feature-branch

プッシュ後、GitHubのPRページにコンフリクトが解消されたことが反映される。

Pull Requestの管理

クローズと再オープン

PRはマージせずにクローズすることができる。
作業の中断、方針変更、重複PRの整理等の場合にクローズを行う。

クローズしたPRは、write権限を持つユーザがいつでも再オープンできる。
再オープン時にはブランチが存在している必要がある。

ベースブランチの変更

PR作成後にマージ先のベースブランチを変更できる。

PRページのタイトル横にある[Edit]ボタンを押下して、ベースブランチのドロップダウンから変更先のブランチを選択する。

ベースブランチの変更時には、以下に示す事柄に注意する。

変更後の差分に応じてコミットが追加または削除される場合がある。
既存のレビューコメントが無効化される場合がある。

コミットの追加

オープン中のPRに対して、ソースブランチに新たなコミットをプッシュすることで変更を追加できる。

# 変更を加えてコミットする
git add .
git commit -m "<レビュー指摘の修正>"

# PRのソースブランチにプッシュする
git push origin feature-branch

プッシュ後、PRページに新しいコミットが自動的に反映される。

リバート

マージ済みのPRをリバートして変更を取り消すことができる。

マージ済みのPRページを開く。
[Revert]ボタンを押下する。
自動的に新しいリバートPRが作成される。
リバートPRをレビューしてマージする。

リバート機能を使用するには、リポジトリへのwrite権限が必要である。

その他の機能

IssueとPRのリンク

PRの説明またはコメントにIssueへの参照を記述することにより、IssueとPRをリンクできる。

キーワードによる自動クローズ

PRがマージされた時点で、関連するIssueを自動的にクローズするキーワードが使用できる。

自動クローズに使用できるキーワードの例を以下に示す。

fixes #123
closes #123
resolves #123

1つのPRで最大10個のIssueを自動クローズできる。

手動リンク

自動クローズが不要な場合は、キーワードなしで #issue-number 形式で参照を記述することにより、IssueとPRを手動でリンクできる。

また、PRページの右側パネルにある[Development]セクションからIssueを手動でリンクすることも可能である。

差分表示オプション

[Files changed]タブでは、コードの差分表示方法を切り替えられる。

差分表示オプション
オプション	説明
Unified	変更前後を上下に並べて表示する。変更内容の全体の流れが把握しやすい。
Split	変更前 (左) と変更後 (右) を左右に並べて表示する。変更箇所の対比が視覚的にわかりやすい。

表示オプションは、[Files changed]タブの右上にある[Display settings] (歯車アイコン) から切り替えられる。

ファイルフィルタリング

変更ファイルが多い場合に、特定のファイルに絞り込んで差分を確認できる。

ファイルツリーナビゲーション
Files changedタブ左側のファイルツリーからディレクトリおよびファイルを選択して表示を絞り込む。
拡張子フィルタ
ファイルタイプ別にフィルタリングして特定の種類のファイルのみ表示する。
CODEOWNERSフィルタ
自分がオーナーとなっているファイルのみ表示する。