Speculative Checks

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 max_parallel_checks value set in your Mergify configuration file. 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 max_parallel_checks is set to 3. In this case, Mergify would create three temporary PRs:

• 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 checks requires the use of the max_parallel_checks setting in your Mergify configuration file. The value for max_parallel_checks determines the maximum number of PRs that can be embarked together for speculative checking.

Here’s a sample configuration:

merge_queue:
  max_parallel_checks: 3

queue_rules:
  - name: default
    merge_conditions:
      - "#approved-reviews-by >= 2"
      - check-success = test

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 max_parallel_checks 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 merge_conditions, that 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 in the queue_rules.

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 setting 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 max_parallel_checks value in the merge_queue section, at the root of your Mergify configuration file. The value can range from 1 to 128, 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.