About merge queues
Configuring continuous integration (CI) workflows for merge queues
-
A merge queue cannot be enabled with branch protection rules that use wildcard characters ( * ) in the branch name pattern. -
A merge queue will wait for required checks to be reported before it can proceed with merging. You must update your CI configuration to trigger and report on merge group events when requiring a merge queue. -
Merge queue and pull requests checks are coupled and configured under branch protection rules or rulesets. For more information, see " Managing a merge queue ."
Triggering merge group checks with GitHub Actions
on:
pull_request:
merge_group:
Triggering merge group checks with third-party CI providers
Managing a merge queue
-
Merge method : Select which method to use when merging queued pull requests: merge, rebase, or squash. -
Build concurrency : The maximum number of merge_group webhooks to dispatch (between one and one hundred ), throttling the total amount of concurrent CI builds. This affects the velocity of merges that a merge queue can complete. -
Only merge non-failing pull requests : This setting determines how a merge queue forms groups of pull requests to be merged. Enabled? Description Yes All pull requests must satisfy required checks to be merged. No Pull requests that have failed required checks can be added to a group as long as the last pull request in the group has passed required checks. If the last pull request in the group has passed required checks, this means that the checks have passed for the combined set of changes in the merge group. Leaving this checkbox unselected can be useful if you have intermittent test failures, but don't want false negatives to hold up the queue. -
Status check timeout : Choose how long the queue should wait for a response from CI before assuming that checks have failed. -
Merge limits : Select the minimum and maximum number of pull requests to merge into the base branch at the same time (between one and one hundred ), and a timeout after which the queue should stop waiting for more entries and merge with fewer than the minimum number.
| |
---|---|
| |
| |
| |
How merge queues work
Successful CI
-
User adds pull request #1 to the merge queue. -
The merge queue creates a temporary branch with the prefix of main/pr-1 that contains code changes from the target branch and pull request #1. A merge_group webhook event of type checks_requested is dispatched and the merge queue will await a response from your CI provider. -
User adds pull request #2 to the merge queue. -
The merge queue creates a temporary branch with the prefix of main/pr-2 that contains code changes from the target branch, pull request #1, and pull request #2, and dispatches webhooks. -
When the GitHub API receives successful CI responses for merge_group branches main/pr-1 and main/pr-2 , the temporary branch main/pr-2 will be merged in to the target branch. The target branch now contains both changes from pull request #1 and #2.
Failing CI
-
User adds pull request #1 to the merge queue. -
The merge queue creates a temporary branch with the prefix of main/pr-1 that contains code changes from the target branch and pull request #1. A merge_group webhook event of type checks_requested is dispatched and the merge queue will await a response from your CI provider. -
User adds pull request #2 to the merge queue. -
The merge queue creates a temporary branch with the prefix of main/pr-2 that contains code changes from the target branch, pull request #1, and pull request #2, and dispatches webhooks. -
When the GitHub API receives a failing status for main/pr-1 , the merge queue automatically removes pull request #1 from the merge queue. -
The merge queue recreates the temporary branch with the prefix of main/pr-2 to only contain changes from the target branch and pull request #2. -
When the GitHub API receives successful CI responses for merge_group branch main/pr-2 , the temporary branch main/pr-2 will be merged in to the target branch without pull request #1 included.
-
Configured CI service is reporting test failures for a merge group -
Timed out awaiting a successful CI result based off the configured timeout setting -
User requesting a removal via the API or merge queue interface -
Branch protection failure that could not automatically be resolved
Jumping to the top of the queue
-
User adds pull request #1 to the merge queue. -
The merge queue creates a temporary branch with the prefix of main/pr-1 that contains code changes from the target branch and pull request #1. A merge_group webhook event of type checks_requested is dispatched and the merge queue will await a response from your CI provider. -
User adds pull request #2 to the merge queue. -
The merge queue creates a temporary branch with the prefix of main/pr-2 that contains code changes from the target branch, pull request #1, and pull request #2, and dispatches webhooks. -
User adds pull request #3 to the merge queue with the jump option which introduces a break in the commit graph. -
The merge queue creates a temporary branch with the prefix of main/pr-3 that contains code changes from the target branch and pull request #3, and dispatches webhooks. -
The merge queue recreates the temporary branches with the prefix of main/pr-1 and main/pr-2 that contain the changes from pull request #3, and dispatches webhooks.