Bitbucket のマージキュー：Add to Merge Queue・設定のしかた・REST API
マージキューのあるブランチでは、プルリクエストはすぐにはマージされません。キューに入り、Bitbucket がそれを入れた後の対象ブランチの姿をビルドし、そのビルドが通った時だけマージします。Bitbucket Cloud では有料プランに、Bitbucket Data Center では 10.2 からあります。以下は Atlassian の Manage pull requests with merge queues（Cloud）、Cloud の REST リファレンス、Data Center の 10.2 と 10.3 のリリースノートからまとめたものです。
Cloud：始める前に
- 有料プラン（Standard か Premium）で、リポジトリの Bitbucket Pipelines が有効なこと。
- マージキューを作って管理できるのはリポジトリの管理者だけです。
- フォークでは使えません。フォークからのプルリクエストを、キューを通して元のリポジトリへマージすることはできません。
Cloud：キューを作って有効にする
- リポジトリの左のサイドバーで、名前の横の More actions（…）から Settings、Workflow、Merge queues、Create a merge queue と進みます。
- Name（
bitbucket-pipelines.ymlのmerge-queuesの下のキーと同じにする）、Target branch（プルリクエストのマージ先のブランチ）、Build concurrency（キューのビルドを同時にいくつ走らせるか）、Merge strategy（Merge commit・Squash・Rebase + merge）を入れて Save。作ったばかりのキューは INACTIVE です。 - 対象ブランチの
bitbucket-pipelines.ymlに、pull-requestsと並べてmerge-queuesの節を足し、キューの名前をキーにします（例：merge-queues:/mergequeue-main:/- step:）。動的パイプラインでも使えます。 - キューの … メニューから Activate。以後、そのブランチへのプルリクエストは、マージチェックが通ると Merge の代わりに Add to Merge Queue を出します。
対応する merge-queues の節がないと、そのブランチへのプルリクエストはマージできなくなって開いたままになり、マージキューの要件を満たしていないという表示が出ることがあります。
Cloud：キューの中で起きること
- Add to Merge Queue のあと、Bitbucket はマージ結果のコミット（対象ブランチがこうなる、という姿）を作り、
bitbucket-merge-queue-*という名前の一時ブランチで、そのコミットにキューのパイプラインを走らせます。ブランチの制限でこの名前のブランチへのコミットを止めないでください。 - ビルドが通ると、Bitbucket は対象ブランチを進め、プルリクエストをマージ済みにします。確かめる順もマージする順も、キューに入れた順です。Build concurrency が 2 以上なら複数のビルドが同時に走りますが、マージはその順のままです。
- ビルドが失敗した時や、対象ブランチと前に並ぶプルリクエストに対してきれいに確かめられない時は、マージされずにキューから外れ、Open のまま残ります。後ろに並ぶプルリクエストのうち、その変更を含んでいたビルドは止められ、その変更を抜いて走り直します。
- キューのビルドの OIDC トークンは、一時ブランチではなく対象ブランチの設定を引き継ぎます。デプロイを管理者だけに絞っている（「Only allow admins to deploy to this environment」）と、マージ後のパイプラインを管理者にできないシステムユーザー
bitbucket-pipelinesが始めることがあるため、デプロイが失敗することがあります。 - ビルドが通ったら自動でマージと同じチェックボックスで、ビルドが通ったら自動でキューに入れることもできます。
Cloud：キューの管理
Merge queues のページ右上の … メニューに、Drain（新しいプルリクエストを受け付けない。キューにあるものはそのまま進む）、Clear（Draining か Inactive の時だけ。全部のプルリクエストを外してビルドを止め、プルリクエストは開いたままに戻る）、Deactivate（キューのプルリクエストを外し、そのブランチは普通のマージに戻る）、Activate、Delete（Inactive か Drained で空の時だけ）があります。同じページで、キューごとに並んでいるプルリクエストを見られます。
Cloud：REST API
- 有効なキューのあるブランチで
POST …/pullrequests/{id}/mergeを呼ぶと、プルリクエストはキューに入ります。asyncが false でも 202 を返し、Locationに task-status の住所を入れます。もう一度呼んでも同じ住所が返ります。キューで使える方法はmerge_commit・squash・rebase_mergeで、指定しなければキューの方法になります。受け付けていないキューは 400、キューを確かめられなかった時は 503（あとでやり直す）です。 GET …/merge/task-status/{task_id}は、キューにある間はPENDINGで、キューが受け取るとqueued_pullrequestが付きます。中身はstatus（QUEUED・PROCESSING・AWAITING_MERGE・MERGE_IN_PROGRESS・REMOVING）と、1 から数えた順番のrankです。マージされるとSUCCESS、マージされずにキューから外れるとエラー（メッセージに Markdown が入ることがある）を返します。…/repositories/{workspace}/{repo_slug}/merge-queuesでキューの一覧（target_branchで絞れる）、…/merge-queues/{uuid}/queueで並んでいるプルリクエストの一覧、DELETE …/merge-queues/{uuid}/queue/{pullrequest_id}で1件をキューから外せます（202。外すのはそのあと）。…/pullrequests/{id}/mergeability/checksには、ブランチがキューを求めている時かプルリクエストがキューにある時、merge_queue_checkが入ります。required・blocking・queuedと、キューのstate（ACTIVE、受け付けるがマージを止めているPAUSED、受け付けないDRAININGとSUSPENDED、キュー不要のINACTIVE）です。
Data Center
Bitbucket Data Center のマージキューは、2026年3月3日の長期サポート版 10.2 で入りました。10.3（2026年5月12日）では、マージキューの Webhook のイベント（マージ結果を用意している時や、キューのブランチを片付けた時など）が加わり、カスケードマージの次のプルリクエストがマージキューのあるブランチ向けの時は、止まって誰かが手でキューに入れるのを待たずに、そのプルリクエストを自動でキューに入れるようになりました。
IntelliJ IDEA でのマージキュー
Pull Request Inbox for Bitbucket は、Lesstep が作っている JetBrains IDE（2024.1 以降）のプラグインです。Bitbucket Cloud と Bitbucket Data Center のプルリクエストを、マージキューを含むマージチェックと一緒に IDE のツールウィンドウに並べます。1.0.49 からは、Bitbucket Cloud でマージキューのあるブランチにマージすると、プルリクエストはキューに入り、プラグインはマージを待たずにキューの何番目かを知らせます。マージされたかは、あとで読み直して確かめます。1.0.50 からは、マージチェックのマージキューの行が、マージがキューを通るか、キューに入っているか（キューが止まっていないか）、キューがいま受け付けていないかを言います。レビューの受け箱とマージチェックは無料、承認・コメント・マージは Pro（30日間の無料試用つき）です。画面は日本語です。
Bitbucket は Atlassian Pty Ltd の商標、IntelliJ IDEA は JetBrains s.r.o. の商標です。このページは Atlassian・JetBrains のいずれとも提携しておらず、承認も受けていません。
ほかに：Bitbucket の自動マージ · Bitbucket のマージチェック · Bitbucket のマージ方法 · プルリクのビルド · IntelliJ IDEA で使える Bitbucket のプルリクエストのプラグインの比較 · English