We recently launched our Batch mode for high output teams where the sequential continuous integration cycles may cause long wait cycles. The main thought process behind batch mode is to run the builds optimistically while falling back when a failure occurs.

Batch mode workflow

There is a simple toggle button on the Merge Rules page to enable this feature. If you do not see the toggle, please reach out to support@mergequeue.com to get access to the batch mode. 

Once the batch mode is turned on, the MQ bot will change its behavior immediately to start creating batches.

Creating Draft PRs

When a PR is labeled to be queued and there is nothing in the queue, the bot will create a new branch with the latest base branch and this PR. Then a Draft PR will be created using this branch.

When a PR is labeled and there are existing queued PRs, all the queued PRs will be combined into a new branch. Then a Draft PR will be created using this branch.

These Draft PRs will trigger the regular CI cycle that will be monitored by the MQ bot. So instead of monitoring the original PR, only the Draft PRs CI will be monitored.

In case the bot fails to create the Draft PR due to merge conflict, the PR will immediately be flagged as failed and dequeued.

On CI completion

If the CI for Draft PR is passed, the original PR is merged in the base branch. The Draft PR itself is closed without merging.

If the CI for Draft PR fails and there’s no other queued PR ahead of this one, the original PR is flagged as failed and dequeued. The Draft PR is closed without merging. Additionally at this point, all pending Draft PRs are closed and the queue is recreated excluding the failing PR. So all corresponding new Draft PRs are created.

If the CI for Draft PR fails and there are more PRs ahead of this one, no action is taken.

Corner cases

1. If the Draft PR CI gets stuck, but a subsequent Draft PR CI passes, we merge all PRs up to that point since the build is stable with all those changes together.
2. If the Draft PR CI passes, but the original PR CI is still running, we will flag the queue as stuck. This is an additional label you can specify in your Batch mode configuration. This should rarely happen as the Draft PR CI starts after the original PR CI, and should finish in that order.

Nuking the current batch

There could be scenarios where the queue is stuck or you want to remove something from the queue. To do this you can remove the label from the PRs that you want to remove and hit the “Reset Queue” button on the Queue list view page. This will nuke your current batch of the queue and close any pending Draft PRs and start over again.

Capping the parallelism

You may want to cap the parallelism to manage your CI capacity. This can be done using the configuration in the batch mode section by specifying the Max bot builds in parallel. The Draft PRs will pause once it hits the cap, and then will add the next once one of the existing one finishes.

Pausing the batching

In addition to capping the parallel builds, they may be need to pause the batching of PRs until a particular PR is merged. This may be needed if you have a long running CIs that gets triggered by modifying specific files. Every subsequent Draft PR will also touch that file causing all subsequent CIs to be long running. In Batch mode configuration, you can specify a GIthub label to Block further bot builds. Once added to a PR, no further Draft PRs will be built on top of it until that PR is merged or dequeued.

Limitations

1. Once a PR is queued, it cannot be dequeued through Github Labels. The only way this would work is by removing the Github Label and resetting the current batch.
2. The bot will ignore any changes that get merged outside of the queue. So it’s recommended to ensure that all developers only use MQ to merge PRs after this.
3. Skip-the-line feature is also not currently supported.

Before you turn on the batch mode

1. Explain the behavior to your team, so they are no surprises when new PRs are being automatically created.
2. Understand your provisioning of parallel CI build capacity. With batch mode, you would be running about 2x the regular CI builds.
3. Make sure you understand any impact from third-party triggers you may configured around creating new PRs.
4. Make sure you understand any impact on third-party analytics you may have set up.
5. It is recommended to enable the bot comments when using batch mode.