GitHub Stacked Pull Requestsを始める最短手順は、GitHub CLIにgh-stack拡張機能をインストールし、gh stack initで最初のブランチを作成、変更をコミットした後、gh stack addで次のレイヤーを重ね、最後にgh stack submitでPull Requestをまとめて作成する流れです。
Stacked Pull Requestsは2026年7月30日にパブリックプレビューとなり、全リポジトリ向けに段階展開が始まりました。github.com、GitHub CLI、GitHub Mobile、GitHub CopilotなどのCoding Agentから利用できます。ただし、リポジトリごとに有効化時期が異なる可能性があり、Merge Queue対応も数週間かけて順次展開されます。(The GitHub Blog)
GitHub Stacked Pull Requestsとは
GitHub Stacked Pull Requestsは、依存関係のある大きな変更を、複数の小さなPull Requestに分割して管理する仕組みです。
通常のPull Requestでは、すべての変更ブランチがmainを宛先にします。一方、Stacked Pull Requestsでは、上のPull Requestが直下のPull Requestのブランチを宛先にします。
たとえば、認証機能を3段階で実装する場合、次の構造になります。
PR3: auth-ui → base: auth-api
PR2: auth-api → base: auth-model
PR1: auth-model → base: mainPR1ではデータモデルだけ、PR2ではAPI部分だけ、PR3ではUI部分だけが差分として表示されます。レビュー担当者は巨大な変更全体ではなく、各レイヤーの目的に絞って確認できます。
| 比較項目 | 1本の大きなPull Request | Stacked Pull Requests |
|---|---|---|
| レビュー対象 | すべての変更 | レイヤーごとの差分 |
| 依存関係 | 説明文やブランチ名で管理 | Pull Requestの順序として明示 |
| 次の作業 | マージを待つ場合がある | 未マージの変更の上で継続可能 |
| ブランチ更新 | 手動のrebaseが増えやすい | gh stack rebaseで連鎖的に更新 |
| マージ | Pull Request単位 | 下から順に一部または全体をマージ |
Stackは同じリポジトリ内のPull Requestを、1本の線形なチェーンとして関連付けます。各Pull Requestは個別にレビューできますが、マージ時には下位レイヤーとの依存関係も評価されます。(GitHub Docs)
2026年7月のパブリックプレビューで変わったこと
2026年7月30日の発表では、Stacked Pull Requestsが全リポジトリ向けのパブリックプレビューとして段階展開されることが案内されました。
利用できる主な環境は次のとおりです。
- github.com
- GitHub CLI
- GitHub Mobile
- GitHub CopilotなどのCoding Agent
gh-stackスキルに対応したその他のCoding Agent
GitHubのPull Requestに組み込まれた機能であるため、既存のレビュー、必須ステータスチェック、CODEOWNERS、ブランチ保護ルールをStackでも利用できます。
ただし、パブリックプレビュー中は仕様変更の可能性があります。また、Merge Queue対応はStacked Pull Requests本体とは別に、数週間かけて段階展開されます。利用するリポジトリにMerge Queue用の操作が表示されない場合は、設定ミスではなく展開待ちの可能性があります。(The GitHub Blog)
gh-stackを使うための前提条件
公式クイックスタートでは、次の環境が前提とされています。
| 項目 | 要件 |
|---|---|
| GitHub CLI | バージョン2.90.0以降 |
| Git | バージョン2.20以降 |
| GitHub認証 | gh auth loginで認証済み |
| リポジトリ権限 | ブランチをpushできること |
| ブランチの配置 | すべて同じリポジトリ内にあること |
最初にバージョンと認証状態を確認します。
gh --version
git --version
gh auth status未認証の場合は、次のコマンドでGitHubへサインインします。
gh auth loginGitHub CLIの古いバージョンを使用している場合は、先にGitHub CLIを更新してください。特にパブリックプレビュー中は、古いCLIでは最新のコマンドやAPIに対応できない可能性があります。(GitHub Docs)
gh-stack拡張機能をインストールする
リポジトリの場所に関係なく、次のコマンドでgh-stack拡張機能をインストールします。
gh extension install github/gh-stackインストール後は、次のコマンドで確認できます。
gh extension list
gh stack --helpすでにインストール済みで最新版へ更新したい場合は、GitHub CLIの拡張機能更新コマンドを使用します。
gh extension upgrade github/gh-stackGitHub CopilotなどのCoding AgentからStackを操作する場合は、拡張機能に加えてgh-stackスキルもインストールします。
gh skill install github/gh-stackgh-stackスキルを導入すると、Coding Agentに「最初のレイヤーだけ実装する」「次の変更を新しいレイヤーとして追加する」「Stackをsubmitする」といった指示を出しやすくなります。(GitHub Docs)
gh-stackで最初のStacked Pull Requestsを作成する方法
ここでは、認証機能を次の3レイヤーに分割する例を使用します。
- データモデル
- 認証API
- ログイン画面
mainブランチを最新状態にする
Stackの土台となるブランチを最新化します。
git switch main
git pull --ff-onlymain以外のブランチを土台にすることもできます。リリースブランチや長期運用中の開発ブランチを指定する場合は、後述する--baseオプションを使用します。
最初のレイヤーを初期化する
最下層となるブランチを作成します。
gh stack init auth-modelこれにより、通常はmainをtrunk、auth-modelをStackの最初のブランチとしてローカル管理が開始されます。
ブランチ名を省略した場合は対話形式で入力できます。
gh stack initdevelopを土台にする場合は、次のように指定します。
gh stack init --base develop auth-modelStackのtrunkは必ずしもデフォルトブランチである必要はありません。最下層のPull Requestが最終的に取り込まれるブランチが、そのStackのtrunkになります。(GitHub Docs)
最初の変更をコミットする
auth-modelブランチで、データモデルやマイグレーションだけを実装します。
git add .
git commit -m "Add user authentication model"この段階では、APIや画面まで一緒に実装しないことが重要です。1つのレイヤーに複数の目的を詰め込むと、Stackを使ってもレビュー負荷は下がりません。
2番目のレイヤーを追加する
次に、認証API用のブランチをStackの上へ追加します。
gh stack add auth-apiauth-apiは現在のauth-modelを起点として作成され、自動的にチェックアウトされます。
API部分を実装してコミットします。
git add .
git commit -m "Add authentication API"3番目のレイヤーを追加する
同じ要領で、ログイン画面用のブランチを追加します。
gh stack add auth-ui変更を実装してコミットします。
git add .
git commit -m "Add login UI"gh stack addは、原則としてStackの最上位ブランチで実行します。下位レイヤーをチェックアウトしている状態で新しいレイヤーを追加できない場合は、先に次のコマンドを実行してください。
gh stack topStackの構造を確認する
Pull Requestを作成する前に、ブランチの順番を確認します。
gh stack viewコンパクトに確認する場合は、次のオプションを使用できます。
gh stack view --shortスクリプトや社内ツールから利用する場合は、JSON形式でも出力できます。
gh stack view --jsongh stack viewでは、ブランチの順番、Pull Requestへのリンク、状態、各ブランチの最新コミットを確認できます。(GitHub Docs)
Pull Requestをまとめて作成する
Stackの準備ができたら、次のコマンドを実行します。
gh stack submitgh stack submitは、各ブランチをリモートへpushし、ブランチごとのPull Requestを作成したうえで、それらを1つのStackとして関連付けます。
今回の例では、次のPull Requestが作成されます。
| Pull Request | headブランチ | baseブランチ |
|---|---|---|
| PR1 | auth-model | main |
| PR2 | auth-api | auth-model |
| PR3 | auth-ui | auth-api |
baseブランチを手動で設定する必要はありません。gh-stackがStackの順番に合わせて設定します。(GitHub Docs)
gh stack pushとgh stack submitの違い
公式クイックスタートでは、次のようにpushとsubmitを順番に実行する例も示されています。
gh stack push
gh stack submitただし、gh stack submit自体にもブランチをpushする処理が含まれています。そのため、最初のStackを作るだけならgh stack submitだけでも進められます。
使い分けは次のとおりです。
| コマンド | 用途 |
|---|---|
gh stack push | ブランチだけをリモートへ反映する |
gh stack submit | ブランチをpushし、Pull Requestの作成・更新とStackへの関連付けを行う |
Pull Requestのタイトルや説明をまだ確定したくない場合は、先にgh stack pushだけを実行してリモートブランチを確認すると安全です。(GitHub Docs)
Pull RequestをDraftまたはレビュー可能状態で作成する
対話形式でgh stack submitを実行すると、各Pull Requestのタイトル、説明、Draftかレビュー可能状態かを画面上で設定できます。
自動生成されたタイトルで対話画面を省略する場合は、次のコマンドを使用します。
gh stack submit --auto--autoを使用した場合、新規Pull Requestは基本的にDraftとして作成されます。すぐにレビュー可能状態で公開する場合は、--openも指定します。
gh stack submit --auto --open実務では、説明文をレイヤーごとに確認できる通常のgh stack submitが適しています。CIや自動化処理から実行する場合に、--autoと--openを使い分けるとよいでしょう。(GitHub Docs)
github.comからStacked Pull Requestsを作る方法
GitHub CLIは必須ではありません。github.com上でもStackを作成できます。
Web画面で新しいStackを作る手順
最初のPull Requestは、通常どおりmainをbaseとして作成します。
次のPull Requestを作るときは、baseブランチにmainではなく、1つ下のPull Requestのheadブランチを指定します。
今回の例では、次のように設定します。
auth-model → main
auth-api → auth-model
auth-ui → auth-api2番目のPull Requestを作成するときに表示される「Create stack」を選択すると、2つのPull RequestがStackとして関連付けられます。その後も、直下のPull Requestのブランチをbaseにしてレイヤーを追加します。
すでにbaseとheadの関係が線形につながっているPull Requestが存在する場合、GitHubがStackへの変換を提案するバナーを表示することもあります。(GitHub Docs)
Web画面だけでは並べ替えできない
Stackの順番を変更する操作は、github.comだけでは完結できません。
ブランチの挿入、削除、統合、名前変更、並べ替えが必要な場合は、GitHub CLIで次のコマンドを使用します。
gh stack modifygh stack modifyは対話型の画面を開き、Stackの構造を編集します。変更後は、次のコマンドでGitHub側へ反映します。
gh stack submitStackの順番を後から変更するとrebaseや競合解消が必要になりやすいため、最初にレイヤーの依存順を設計してから作業を始める方が安全です。(GitHub Docs)
レビュー指摘を下位レイヤーへ反映する方法
Stackの途中にあるPull Requestで修正依頼を受けた場合、最上位ブランチで回避的な修正を入れるのではなく、その変更を所有するブランチへ戻って修正します。
たとえば、auth-apiで修正が必要になった場合は、次のように操作します。
gh stack checkout auth-api
# 修正後
git add .
git commit -m "Fix authentication validation"
gh stack rebase --upstack
gh stack pushgh stack rebase --upstackは、現在のブランチから上にあるレイヤーを連鎖的にrebaseします。これにより、auth-uiも修正後のauth-apiを含んだ状態になります。
ブランチ名を使わず、現在位置から上下に移動することもできます。
| コマンド | 動作 |
|---|---|
gh stack up | 1つ上のレイヤーへ移動 |
gh stack down | 1つ下のレイヤーへ移動 |
gh stack top | 最上位へ移動 |
gh stack bottom | 最下位へ移動 |
gh stack trunk | mainなどのtrunkへ移動 |
gh stack switch | 一覧からブランチを選択 |
下位レイヤーを修正した後は、上位レイヤーへ変更を伝播させるためのrebaseを忘れないことが重要です。(GitHub Docs)
rebaseで競合した場合の対処方法
Stacked Pull Requestsは、ブランチ間のコミット履歴が線形であることを要求します。そのため、trunkが更新された場合や下位レイヤーを修正した場合は、連鎖的なrebaseが必要になります。
Stack全体をrebaseする場合は、次のコマンドを実行します。
gh stack rebase競合が発生した場合は、競合箇所を修正してステージした後、処理を続行します。
git add .
gh stack rebase --continue処理前の状態に戻したい場合は、次のコマンドで中止できます。
gh stack rebase --abortrebase後はブランチの履歴が変わるため、次のコマンドでリモートを更新します。
gh stack pushgh stack pushはrebase済みブランチの更新に--force-with-lease相当の確認を使用します。通常の--forceより安全ですが、同じブランチを複数人で直接編集する運用では、事前に変更状況を確認してください。(GitHub Docs)
Branch Protectionと必須チェックはどう評価されるか
Stack内のPull Requestは、直接のbaseブランチではなく、Stack全体のtrunkに設定されたルールを基準に評価されます。
たとえば、次のStackを考えます。
main ← PR1 ← PR2 ← PR3PR2の直接のbaseはPR1のブランチですが、必須レビューやステータスチェックは、Stackのtrunkであるmainのルールを基準に評価されます。
| ルール | Stackでの評価方法 |
|---|---|
| 必須レビュー | Stackのtrunkを基準に評価 |
| 必須ステータスチェック | Stackのtrunkを基準に評価 |
| CODEOWNERS | Stackのtrunkにある定義を基準に評価 |
| コードスキャン | Stackのtrunkを基準に評価 |
| GitHub Actions | 各Pull Requestがtrunkを対象とするものとして実行 |
既存のBranch ProtectionやRulesetを解除する必要はありません。ただし、上位のPull Requestをマージするには、そのPull Requestだけでなく、下にあるすべてのPull Requestが要件を満たしている必要があります。(GitHub Docs)
GitHub Actionsの実行回数が増える点に注意する
pull_requestイベントでmainを対象にしているGitHub Actionsは、Stack内のすべてのPull Requestで実行されます。
3レイヤーのStackなら、同じワークフローが原則として3回実行されます。各レイヤーの品質を確認できる一方、ビルド時間やGitHub Actionsの使用量が増える可能性があります。
高コストな結合テストだけをStack最上位のPull Requestで実行する場合は、Stackメタデータを条件に利用できます。
- name: Run expensive integration tests
if: >
github.event.pull_request.stack == null ||
github.event.pull_request.stack.position ==
github.event.pull_request.stack.size
run: npm run test:integrationこの条件では、通常のPull Requestではテストを実行し、Stackの場合は最上位のPull Requestだけで実行します。
ただし、必須ステータスチェックに指定しているジョブを安易にスキップすると、マージ要件との整合性が崩れることがあります。最初は必須ではない高コストテストや、重複しても品質上の意味が薄い処理から最適化するのが安全です。(GitHub Docs)
Stacked Pull Requestsをマージする方法
Stacked Pull Requestsは、trunkに最も近い下位レイヤーから順番にマージされます。
3つのPull Requestがある場合、選択するPull Requestによって次のように動作します。
| マージ対象 | 実際にマージされる範囲 |
|---|---|
| PR1 | PR1だけ |
| PR2 | PR1とPR2 |
| PR3 | PR1、PR2、PR3のすべて |
途中のPR2だけを単独でマージし、PR1を残すことはできません。選択したPull Requestから最下位の未マージPull Requestまでが、連続したグループとして処理されます。
GitHub CLIからマージする場合は、次のコマンドを使用します。
gh stack merge現在のStack全体を確認なしでSquashマージする例は次のとおりです。
gh stack merge --yes --squashStackでは、Merge commit、Squash、Rebaseの3つのマージ方式を使用できます。直接マージする場合、選択した範囲はすべて成功するか、すべて失敗するかの一括処理になります。(GitHub Docs)
一部だけマージした後の上位レイヤー
PR1だけをマージすると、PR2は自動的にtrunkを直接参照する最下位レイヤーへ移動します。さらに上のPull Requestは開いたまま維持されます。
ローカル環境をGitHub側の状態に合わせる場合は、次のコマンドを実行します。
gh stack sync --pruneこのコマンドは、trunkの更新、残りのブランチのrebase、push、Pull Request状態の同期、マージ済みローカルブランチの削除をまとめて実行します。(GitHub Docs)
Merge Queueを利用する際の注意点
Stacked Pull RequestsのMerge Queue対応は、2026年7月30日の発表時点では数週間かけて段階展開される予定です。そのため、リポジトリによって利用できる時期が異なります。
対応済みのリポジトリでは、Stack内のPull Requestが依存順にMerge Queueへ追加されます。下位のPull Requestがキューから除外された場合、それより上のPull Requestもキューから外れます。
また、Merge Queue経由では、Stackを一度に追加しても、キューの構成によって複数のmerge groupに分割される場合があります。直接マージ時の「1回の原子的な操作」と、Merge Queueでの処理を同じものとして扱わないようにしてください。(The GitHub Blog)
パブリックプレビュー時点の主な制限
導入前に、次の制限を確認しておく必要があります。
| 制限・注意点 | 実務への影響 |
|---|---|
| 段階展開中 | リポジトリによってまだ利用できない場合がある |
| 同一リポジトリ限定 | fork元とfork先をまたぐStackは作れない |
| 線形構造が必須 | 途中から枝分かれする構造は作れない |
| GitHub Desktop非対応 | WebまたはCLIなどを利用する必要がある |
| Webでは並べ替え不可 | gh stack modifyが必要 |
| Auto-merge非対応 | 通常のAuto-merge前提の運用はできない |
| 完了したStackは再拡張不可 | 全PRマージ後に追加すると新しいStackになる |
| 従来のPRマージAPIではマージ不可 | BotやChatOpsはStacks APIへの対応が必要 |
| サーバー側rebaseは署名されない | 署名必須リポジトリではCLIからrebaseする |
特に、forkを利用するオープンソース開発、Auto-mergeを多用するチーム、独自BotでPull Requestをマージしている組織では、既存フローとの互換性を確認してから導入してください。(GitHub Docs)
利用できない場合の確認ポイント
gh stackで「有効ではない」と表示される
gh-stackでは、Stacked Pull Requestsがリポジトリで有効になっていない場合に、終了コード9が使用されます。
2026年7月30日以降も段階展開中であるため、次を確認してください。
- GitHub CLIと
gh-stackを更新しているか - 正しいGitHubアカウントで認証しているか
- 対象リポジトリへpushできるか
- 数日置いても同じ状態か
- GitHubのPull Request画面にStack関連の項目が表示されるか
CLIや認証に問題がなく終了コード9になる場合は、リポジトリへの機能展開待ちである可能性があります。(GitHub Docs)
Pull Requestの差分が大きすぎる
上位Pull Requestのbaseがmainになっていないか確認してください。
正しい構造は、次のように直下のブランチをbaseにする形です。
auth-ui → auth-api
auth-api → auth-model
auth-model → maingithub.comで手動作成した場合は、baseブランチの選択ミスが起きやすくなります。CLIから作成し直せる場合は、gh stack submitにbase設定を任せる方が確実です。
現在のPull Requestが成功しているのにマージできない
上位Pull Requestをマージするには、その下にあるPull Requestも次の条件を満たす必要があります。
- 必須レビューが完了している
- 必須ステータスチェックが成功している
- CODEOWNERSの承認要件を満たしている
- ブランチ間の履歴が線形になっている
非線形になっている場合は、次のコマンドを実行します。
gh stack rebase
gh stack pushコミット署名が失われる
GitHubのWeb画面にある「Rebase stack」を使用すると、サーバー側で作られたコミットには署名が付きません。
署名付きコミットが必須のリポジトリでは、ローカルの署名設定を利用して次のように処理します。
gh stack rebase
gh stack pushサーバー側rebaseを実行する前に、リポジトリの署名必須ルールを確認してください。(GitHub Docs)
Stacked Pull Requestsが適しているケース
Stacked Pull Requestsは、変更量が多いだけでなく、変更同士に明確な依存関係がある場合に効果を発揮します。
たとえば、次のような開発に適しています。
- データベース変更、API、画面を順番に実装する機能追加
- 基盤クラスを変更した後、複数の利用箇所を段階的に移行するリファクタリング
- 大規模なフレームワークやライブラリの更新
- Coding Agentが生成した大量の変更をレビュー可能な単位へ分割する場合
- 下位レイヤーのレビュー中も、依存する次の作業を進めたい場合
一方、変更同士が独立しており、どの順番でもマージできる場合は、通常の個別Pull Requestにした方が管理しやすくなります。
また、数ファイルだけの小さな修正を無理にStackへ分割すると、Pull Requestの作成、CI、レビュー、rebaseの回数だけが増えます。依存関係を説明できないレイヤーは、Stackに含めないことが判断基準です。
導入時は2レイヤーのStackから試す
最初から大規模な機能開発へ導入するのではなく、まずは検証用リポジトリや小さな変更で、2レイヤーのStackを作るのが安全です。
最低限、次の流れを確認します。
gh extension install github/gh-stack
gh stack init first-layer
# 変更してコミット
gh stack add second-layer
# 変更してコミット
gh stack view
gh stack submit作成後は、各Pull Requestの差分、Branch Protection、必須チェック、GitHub Actionsの実行回数、マージ後の自動的なbase変更まで確認してください。
問題がなければ、データモデル、API、UIのように依存順が明確な開発へ広げます。Stacked Pull Requestsは、単にPull Requestを細かくする機能ではありません。変更の依存関係を明示し、レビュー可能な順序に設計することで効果を発揮します。
コメント