View as Markdown

Merge Schedules

How the merge queue tests a pull request before its merge schedule opens, and how it keeps that pull request from holding up the ones that can merge now.


A queue rule can limit when its pull requests merge with a schedule in its merge_conditions. Outside that window, a pull request’s merge schedule is closed: it stays in the queue and does not merge, however green its checks are. Mergify tests it ahead of the window, so it merges as soon as the window opens, and keeps it from holding up the pull requests that can merge now.

Use one when some pull requests should only land at certain hours, such as dependency updates while someone is around to watch them deploy.

Add the schedule to the merge_conditions of the queue rule that should wait:

.mergify.ymlyaml
queue_rules:
- name: dependencies
queue_conditions:
- author = dependabot[bot]
merge_conditions:
- check-success = ci
- or:
- label = hotfix
- schedule = Mon-Fri 09:00-11:00[Europe/Paris]
- name: default
merge_conditions:
- check-success = ci

Here, dependency updates merge on weekday mornings, unless labeled hotfix, and every other pull request merges as soon as its checks pass. In the figures, #21 is a dependency update and the others come from your team.

Which schedules Mergify recognizes

Section titled Which schedules Mergify recognizes

Mergify treats a merge schedule as closed only when the queue rule’s conditions prove it:

  • A schedule or current-datetime condition listed in merge_conditions, or nested in an and, closes the rule for every pull request outside its window.

  • In an or with label or author conditions, as above, it closes the rule only for the pull requests that match none of them. A dependency update labeled hotfix has its schedule open at any hour.

When a schedule sits in an or with any other condition, Mergify treats it as open: the pull request is tested in its turn and, if its checks pass outside the window, waits at its place like any other unmet merge condition.

Testing before the window opens

Section titled Testing before the window opens

A pull request whose schedule is closed keeps its place in the queue, but is tested behind the pull requests that can merge now, before its window opens. Once its checks pass, its batch waits with the batch status waiting_schedule and merges when the window opens.

waiting checks running 1st 2nd 3rd Order queued #21 #21 #22 #22 #23 #23 Order tested at night #22 #22 #23 #23 #21 #21 waiting checks running 1st 2nd 3rd Order queued #21 #21 #22 #22 #23 #23 Order tested at night #22 #22 #23 #23 #21 #21
#21's schedule is closed, so #22 and #23 are tested first and #21 behind them.

Giving up its place in the queue

Section titled Giving up its place in the queue

A batch is tested on top of the batches ahead of it, so one waiting for its window would hold up everything behind it. Instead, it gives up its place to any batch behind it that could merge sooner, and is tested again behind it. A batch holding pull requests that can merge now and ones that cannot is split the same way, when that merges the first ones sooner.

waiting for its schedule checks passed checks running 1st 2nd After 11:00 #21 #21 #22 #22 After #21 gives way #22 #22 #21 #21 waiting for its schedule checks passed checks running 1st 2nd After 11:00 #21 #21 #22 #22 After #21 gives way #22 #22 #21 #21
#21 cannot merge before 09:00, so it gives up its place: #22 is tested again without it and merges.

max_parallel_checks caps how many batches run their checks at once, and a per-scope capacity caps them within a scope. A batch tested ahead of its schedule only borrows a slot no pull request needed: when one that can merge now is waiting for a slot, the batch gives it back and is tested again once a slot is free. It does so whatever allow_checks_interruption is set to: a schedule is not a priority.

checks running waiting Slot 1 Slot 2 Slot 3 Waiting Every slot taken #21 #21 #24 #24 #25 #25 #23 #23 After #21 gives its slot #23 #23 #24 #24 #25 #25 #21 #21 checks running waiting Slot 1 Slot 2 Slot 3 Waiting Every slot taken #21 #21 #24 #24 #25 #25 #23 #23 After #21 gives its slot #23 #23 #24 #24 #25 #25 #21 #21
Every slot is taken, so #21, tested ahead of its window, gives its slot to #23, which can merge now.

What you see on the pull request

Section titled What you see on the pull request

Giving up its place or its check slot interrupts the checks of the waiting pull request and of those batched with it or tested on top of it. They report the schedule-blocked-ahead-yielded dequeue reason and stay in the queue, to be tested again on their own.

Was this page helpful?