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.
How Speculative Checks WorkSection titled How Speculative Checks Work
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.
Configuring Speculative ChecksSection titled Configuring Speculative Checks
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:
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.
Handling Issues with Speculative ChecksSection titled Handling Issues with Speculative Checks
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.
Failed ChecksSection titled Failed Checks
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.
Changes to Queue Rules or PRsSection titled Changes to Queue Rules or 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.
New Commit on the Base BranchSection titled New Commit on the Base Branch
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
Important ConsiderationsSection titled Important Considerations
While speculative checks can greatly speed up the merging process, there are a few important considerations to keep in mind when using this feature:
Branch Protection SettingsSection titled Branch Protection Settings
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.
Parallel Checks LimitSection titled Parallel Checks Limit
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.
Queued PR ChangesSection titled Queued PR Changes
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.
Transferring LabelsSection titled Transferring Labels
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.