Accelerates the merging process by testing the compatibility of multiple queued pull requests in parallel.
In the context of software development, waiting for pull requests (PRs) to merge one after another can be time-consuming, especially when each one needs to pass through continuous integration (CI) pipelines. This is where Speculative Checks come into play.
Speculative checks, as part of Mergify's queuing feature, facilitate the simultaneous testing of multiple PRs to speed up the merging process. They test a set of PRs together to ensure compatibility before committing them to the main branch.
At its core, speculative checks aim to hasten the PR merging process by proactively identifying potential merge conflicts or test failures, thereby saving valuable development time. This introduction will guide you in grasping the concept of speculative checks, their functionality, and the optimal way to set them up.
The speculative checks functionality operates by grouping multiple pull
requests together based on their order in the queue and the
speculative_checks value set in your
queue_rules. These PRs are then tested
together in a speculative manner, meaning they are combined and tested as if
they were going to be merged.
Consider a situation where you have 5 pull requests (PR #1 to PR #5) and
speculative_checks is set to 3. In this case, Mergify would create three
- Temporary PR #1: Combines PR #1
- Temporary PR #2: Combines PR #1 and PR #2
- Temporary PR #3: Combines PR #1, PR #2, and PR #3
These temporary PRs are created to facilitate parallel testing via your
continuous integration (CI) pipelines. The goal is to validate the merged
outcome of every PR in the queue in advance, ensuring they meet the
queue_rules merge conditions. If any of the PRs fails, it is removed from the
queue, identifying it as the source of the failure.
The result is an efficient PR processing workflow that ensures rapid and successful merges while minimizing the risk of merge conflicts and test failures.
Mergify does not merge the temporary draft PRs, but rather merges the original PR once they pass the speculative checks. It is possible to merge the draft PR themselves — see Merging the Draft PRs.
Configuring speculative checks requires the use of the
setting in your
queue_rules. The value for
the maximum number of PRs that can be embarked together for speculative
Here's a sample configuration:
queue_rules:- name: defaultspeculative_checks: 3merge_conditions:- "#approved-reviews-by>=2"- check-success=Travis CI - Pull Request
In the above example, Mergify will embark up to 3 PRs together for speculative checking. Note that this doesn't mean that only 3 PRs will be in the queue — it simply dictates the maximum number of PRs that can be scheduled together for simultaneous testing.
Remember, speculative checks are optional and the use of this feature depends
on your specific project needs. You may need to adjust the
value depending on the CI resources available and the typical size and
complexity of PRs in your project.
When speculative checks are underway, certain issues can lead to changes in the way the PRs are being processed. Here's what happens in the event of various issues.
If any of the embarked PRs fail the checks defined in
PR is removed from the queue. The checks are then re-run on the remaining PRs.
If an embarked PR no longer matches the
queue_conditions, it is removed
from the speculative checks. Similarly, all PRs embarked after the removed PR
are also disembarked and re-embarked according to their new order in the queue.
This situation can occur when there are changes to the PR itself (such as a new
commit or a change in labels) or changes to the
queue_conditions. In either
case, the queue is updated and the speculative checks process is restarted.
If a new commit is pushed to the base branch while speculative checks are underway, Mergify resets the process. The checks start over again with the updated base branch. This ensures that the merged code will be up-to-date with the latest version of the base branch.
In all these scenarios, the speculative checks process is dynamic and adjusts
itself to the changes, ensuring that the merged code meets the criteria defined
While speculative checks can greatly speed up the merging process, there are a few important considerations to keep in mind when using this feature:
Speculative checks operate by creating temporary pull requests, which merge
multiple PRs with the base branch. This process requires the branch protection
Require branches to be up to date before merging to be disabled.
This does not mean that Mergify will test outdated PRs, but it will merge the original pull requests once its speculative checks is finished. The original PR won't be up-to-date according to GitHub, which means using this setting would block the merge.
You can set the number of parallel speculative checks by adjusting the
speculative_checks value in
queue_rules. The number can range from 1 to 20,
depending on your requirements and available CI resources.
Remember that changes to PRs or the queue can disrupt the speculative checks
process. If a PR is updated or changed in a way that it no longer meets the
queue_rules, it will be removed from the queue, and the order of checks will
be updated. In such cases, the process resets, and the remaining PRs are
rechecked in their new order.
If you rely on labels for some reason (e.g., triggering workflows) and would like to have those copied on the draft PRs that Mergify creates, you can use the mergify-merge-queue-labels-copier GitHub Action to copy the labels from the original pull requests to the draft PR.