What is a Merge Queue?#

A merge queue is essentially a lineup of pull requests waiting their turn to be tested, updated if necessary, and finally merged into the main codebase.

These pull requests are submitted by developers and then selectively added to the queue by maintainers after they pass certain checks and receive approval. This system ensures that only verified and approved changes are queued for merging.

Why Use a Merge Queue?#

The primary benefit of a merge queue comes into play when dealing with one of the most common issues in software development: merging outdated pull requests.

Consider this scenario: the main branch of your repository passes its continuous integration (CI) tests, and a pull request is created which also passes the CI tests. Everything seems fine until a new commit is pushed to the main branch, potentially making the pull request outdated even though it still appears valid and mergeable.

If you proceed to merge without rechecking, the CI tests might fail, leading to surprises and additional work like rebasing and updating the pull request.

You could run CI only on the feature branch head, but this risks compatibility issues with the main branch. Alternatively, requiring all feature branches to be up-to-date before merging is time-consuming and costly.

How Does a Merge Queue Solve This?#

A merge queue addresses these challenges efficiently. It automatically updates each pull request in the queue by merging the latest main branch changes into the feature branch. This ensures the pull request is always tested against the most current version of the code. If the CI tests pass, the merge proceeds; if not, the pull request is removed from the queue for further updates.

This system is particularly advantageous when multiple pull requests are involved. The merge queue manages these by scheduling updates and merges sequentially, ensuring each pull request is current before merging.