Parallel 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 Parallel Checks come into play.

Parallel 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, parallel 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 parallel checks, their functionality, and the optimal way to set them up.

The parallel 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 parallel 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 parallel 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 parallel 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, parallel 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 parallel 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 queue. Similarly, all PRs embarked after the removed PR are also disembarked and re-embarked according to their new order in the queue, making Mergify launches new checks.

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 check process is restarted.

If a new commit is pushed to the base branch while parallel 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 parallel checks process is dynamic and adjusts itself to the changes, ensuring that the merged code meets the criteria defined in the queue_rules.

While parallel checks can greatly speed up the merging process, there are a few important considerations to keep in mind when using this feature:

Parallel 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 parallel 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 parallel 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.