GitHub Merge Queue
Automatically merge pull requests with real-time status checks by Merge Freeze.
Merge Freeze supports GitHub's Merge Queue, a branch protection rule add-on that automates status checks when pull requests are 1) enqueued and 2) ready to merge.
If you installed Merge Freeze prior to May 17, 2023, see Troubleshooting first to ensure your Organization shares sufficient API scopes with our GitHub Application.
Get Started
Connect your desired GitHub repository to Merge Freeze from the Merge Freeze dashboard > "+ New Project" interface.
Then visit the repository on GitHub and navigate to Settings > Branches > Edit/Create a Branch Rule.
Ensure "Require status checks to pass before merging" is selected, then type "mergefreeze" (no spaces) into the search box and select the Merge Freeze application.
Next, scroll down and check "Require merge queue," followed by saving these settings.
You're done! Merge Freeze will now send status checks to your GitHub merge queue.
How it Works
Here's what happens when Merge Freeze is included as a "status check" for a branch protection rule with Merge Queue enabled. See Demonstration below for a screenshot-driven explanation.
Click "merge when ready" from a pull request on GitHub.
GitHub sends a "pull_request.enqueued" (not documented!) webhook event to Merge Freeze.
Merge Freeze sends back the status of your project's main branch (configured inside the Merge Freeze dashboard). This status is either "success" or "failure" pending whether the branch is unfrozen or frozen, respectively.
Once* the branch is unfrozen, Merge Freeze will send a status back to GitHub letting it know the PR is OK to be enqueued to the Merge Queue. Note: all of your branch rule "status checks" send a ping like this, thus all status checks must send a "success" state for the PR to enter your Merge Queue.
Your pull request enters the Merge Queue. When it reaches the head (top**) of the queue, a "merge_group.checks_requested" webhook event is sent to Merge Freeze for a final check.
Just like Step 3, Merge Freeze again sends back the status of your project's branch.
If this status is "success" (along with other branch rule checks), your pull request will be merged automatically. If not, the pull request will be kicked from the Merge Group and return to "merge when ready" state.
*If your branch is already unfrozen when the payload from Step 2 is received, Merge Freeze will immediately send a "success" status check. If your branch is frozen, Merge Freeze will send a "failure" status check. Later, when you unfreeze the branch via Merge Freeze, we'll send a new "success" ping to restart the enqueue process. **GitHub allows Merge Queue users to run parallel builds. Thus "head/top" does not necesarily mean the #1 slot of a queue, but rather "within the range of parallel builds."
In other words, Merge Freeze may send a 2nd and final status update several minutes before the automatic merge is to occur, which can lead to false positives (see Edge Cases below).
Demonstration
Opening a pull request that already has Merge Queue enabled, with Merge Freeze as one of the required status checks.
Opening a pull request that is already failing the Merge Freeze status check.
Pull request that passed the Merge Freeze (+ other, if applicable) status checks, waiting to be merged from the Merge Queue.
Pull request in the merge queue, awaiting final status check.
Pull request in the merge queue, after failing the Merge Freeze status check. (This will soon after be kicked out of the queue).
Pull request in the merge queue, after passing the Merge Freeze status check.
Troubleshooting
If you installed Merge Freeze prior to May 17, 2023, your integration with us does not support the Merge Queue scope by default.
To add support for Merge Queue, visit your Organization on GitHub and navigate to Settings > GitHub Apps. You should see a request for additional permissions by Merge Freeze.
Click "review request" and accept our new API scope -- Merge queues read/write.
After accepting the new permissions, check out the top of this guide to get started with Merge Queue. Note that an Organization administrator may be required to complete these steps.
Edge Cases
Suppose you have a CI build that takes several minutes to run. When your pull request is enqueued, Merge Freeze will reply immediately with a "success" status if the branch is unfrozen. However your build may run for another 10 minutes. Thus it's possible your branch's status could change from unfrozen to frozen during this build period, yet GitHub's Merge Queue wouldn't be aware because the Merge Freeze status check already passed.
To avoid this type of false positive (CI build passes, branch is frozen), it may be a good idea for teams with long CI build times to implement a GET hook that double checks a branch's unfrozen status at the end of a build, then returns a "failure" status to GitHub even if tests and other workflows were successful.
Ideally, GitHub will someday allow developers to sequence their branch rule status checks. With this functionality, developers can simply make Merge Freeze the final check, guaranteeing real-time status updates for imminent merges.
Last updated
