Merge queues
How Limn works with GitHub's merge queue and lands one pull request at a time per repository.
There are two queues in Limn, and they are different things. GitHub’s merge queue is a repository setting: GitHub tests each pull request against the ones ahead of it and merges them in turn. Limn’s landing order is how Limn lands the pull requests you armed with Merge when ready on a repository without a merge queue: one at a time, in the order you armed them. Limn never mixes up the two in what it shows you.
#The two queues side by side
| GitHub’s merge queue | Limn’s landing order | |
|---|---|---|
| Who runs it | GitHub | Limn, on your computer, while it is running |
| Applies to | Repositories with a merge queue | Pull requests you armed, on repositories without one |
| Shown as | In the merge queue | Waiting its turn |
| Order | GitHub’s | The order you armed them |
#GitHub’s merge queue
On a repository whose branch uses a merge queue, GitHub refuses a direct merge, so Limn does not offer one. The merge button becomes Add to merge queue, and Merge when ready becomes Queue when ready.
- Open the pull request’s Overview tab and press Show actions.
- Press Add to merge queue. GitHub now runs its checks and merges it in turn.
- To take it out, press Remove from queue.
While a pull request is queued, the Overview tab shows its place and estimated time, read from GitHub when you open it. The Pending board shows that it is queued but not its place, because the board does not ask GitHub when it opens. If GitHub is taking it out of the queue because it can no longer merge, the card says so.
With Queue when ready, Limn updates the branch from the base branch if needed, before it first adds the pull request to the queue, and adds it once the required reviews are in. It never updates a branch that is already in the queue. If the queue refuses it because required checks are still running, Limn waits and tries again; it does not give up.
#Limn’s landing order
When you arm several pull requests on a repository without a merge queue, only the first in line is updated and merged. The others show Waiting its turn and their place, for example “Waiting its turn — 2 of 5 on this repo”, and Next up on this repo for the second. When one merges, the next is updated against the new base branch and merged in turn. So five pull requests cost five branch updates and five CI runs, not one for every pair.
- If the first in line has failing checks or conflicts, it lets the next one through and keeps its place: Waiting — checks failed, letting the next PR through.
- A pull request that stops for its own reason, such as a new commit or a closed pull request, stops at once, wherever it is in line.
- A waiting pull request that conflicts says so, with its place, rather than just “waiting its turn”.
#Why it helps
Merging a batch of pull requests on one repository is where branches fall behind and CI runs pile up. Limn either hands the batch to GitHub’s queue or lands it in order itself, and tells you plainly which one is happening.