Learn how to order your pull requests in the queue by priority.
In the realm of software development, the ability to effectively prioritize tasks is a critical skill that can greatly improve efficiency and productivity. When dealing with multiple pull requests, it becomes imperative to properly prioritize them to ensure a smooth and efficient merging process. That's where Mergify's priority rules come into play.
Priority rules are an optional but highly useful feature in Mergify's arsenal. They offer you a more refined control over how your pull requests are ordered within a queue. By applying these rules, you can assign priorities to pull requests based on the conditions you define. This makes it possible to influence the position in which a pull request is added to the queue, thereby helping you handle urgent tasks more promptly.
Priority rules in Mergify are a set of guidelines that determine the order of
pull requests within a merge queue. They apply a priority — which could be a
keyword such as
high or a numerical value — to a pull
request based on conditions you've defined. When using numerical value, the
value can be between 1 and 10,000.
When a pull request is added to a queue, each priority rule is evaluated against its conditions. This assessment determines where the pull request will be placed in the queue. If multiple rules match the pull request, the one with the highest priority value is chosen.
If no priority rules matches, Mergify assignes the
medium priority to a
pull request. This is the default and is not configurable.
Here is a glimpse into the structure of a priority rule:
queue_rules:- name: defaultqueue_conditions:- "#approved-reviews-by>=2"- check-success=Travis CI - Pull Requestpriority_rules:- name: high priorityconditions:- label=urgentpriority: high- name: low priorityconditions:- label=refactorpriority: low
In the above configuration:
priority_rulessection sets up priority rules for the queue named
Two priority rules,
low priority, are defined.
Each rule contains conditions (
label=refactor, respectively) which, if met, apply a certain priority to the pull request (
low). Pull requests that match no priority rules get assigned to
The name under each rule is just an identifier and doesn't impact the functioning of the rule.
The power of priority rules lies in their flexibility. You can set up as many rules as you need, tailored to your specific workflow. Whether it's to prioritize bug fixes or to push feature updates to the back, priority rules offer you the control you need over your merge queue.
Defining priority rules is straightforward and involves the following steps:
Choose a queue: Priority rules are tied to a specific queue. So, first, choose the queue where you want to apply these rules.
Define priority levels: Decide on the levels of priority you want to establish for your pull requests. You can use either keywords (
high) or numerical values for this purpose.
Set up conditions: Define the conditions under which a pull request should be assigned a particular priority level. These conditions can be based on any pull request attribute.
|Key name||Value type|
Name of the rule.
list of undefined
The list of conditions that needs to match to assign priority to the pull request.
The priority of the pull request.
The textual priorities have the following numerical values:
Let's look at an example:
queue_rules:- name: defaultqueue_conditions:- "#approved-reviews-by>=2"- check-success=TeamCitypriority_rules:- name: urgent fixesconditions:- label=urgent- label=bugpriority: high- name: low-priority tasksconditions:- label=refactorpriority: 10
In this configuration:
We are defining priority rules for the
Two priority levels are set up:
highfor urgent bug fixes and
10for refactoring tasks.
The conditions for the
highpriority level are that the pull request has labels
The condition for the low-priority tasks is that the pull request has the
Remember that a pull request can match multiple rules. In such cases, Mergify picks the rule with the highest priority value. So it's a good idea to define your rules considering all possible scenarios.
allow_checks_interruption option plays a critical role in managing the
sequence of pull requests within the merge queue. When set to
true, which is
the default setting, this option allows the interruption of ongoing
speculative checks if a pull request with higher priority
enters the queue.
In practice, this means that if a high priority pull request is added to the queue, Mergify can stop the checks on the current pull request in order to prioritize the high priority one.
allow_checks_interruption is set to
false, Mergify will not
interrupt the checks. Instead, a pull request with a higher priority will be
inserted just after the pull requests that currently have checks running. This
ensures the continuity of the testing process while still respecting the
priority order in the queue.
queue_rules:- name: defaultmerge_conditions:- "#approved-reviews-by>=2"- check-success=TeamCityallow_checks_interruption: falsepriority_rules:- name: urgentconditions:- label=urgentpriority: high- name: normalconditions:- label=normalpriority: low
In this configuration,
allow_checks_interruption is set to
means if a pull request with the
urgent label (which has a higher priority)
enters the queue, it will not interrupt the checks running on a pull request
normal label. Instead, it will wait for the
normal pull request's
checks to complete before starting its own checks.
Beyond the basic use of priority rules, you can leverage advanced features to fine-tune how your pull requests are prioritized in the queue.
While the keywords (
high) provide an easy way to define
priority, they might be restrictive in some cases. If you need more granular
control, consider using numerical values for priority. The higher the number,
the higher the priority.
priority_rules:- name: extremely urgentconditions:- label=criticalpriority: 5000
In this rule, pull requests labeled
critical are given a very high priority.
There is no rule that prevents you from mixing keyword and numerical values in
your priority definitions. This could be useful in scenarios where you want to
distinguish between a general set of important tasks (assigned a keyword like
high) and extremely important tasks (assigned a high numerical value).
priority_rules:- name: important taskconditions:- label=importantpriority: high- name: critical taskconditions:- label=criticalpriority: 5000
In this configuration,
critical tasks are treated with the utmost urgency,
important tasks also receive high priority but are placed after
critical tasks in the queue.
The conditions for priority rules are not limited to simple label checks. You can make use of any condition syntax available in Mergify. This includes checks for review status, authorship, file paths, and more. This opens up a wide array of possibilities for defining intricate priority systems based on your team's workflow.
Here's an example that gives high priority to pull requests that modify the
priority_rules:- name: core changesconditions:- files~=^src/priority: high
These are just a few ways to get the most out of Mergify's priority rules. By thinking about your team's needs and workflow, you can leverage these advanced usage scenarios to create a priority system that best serves your project.
Even with the best planning and understanding, you may run into issues when setting up or managing priority rules. Here are some common problems and their solutions:
If you find that a priority rule is not applied as expected, there may be several reasons:
Check the conditions of the priority rule. Ensure that the pull request matches the conditions specified in the priority rule.
The priority rule could be overridden by another rule with a higher priority. Remember, if a pull request matches multiple rules, the rule with the highest priority will be retained.
There might be an error in the syntax or formatting of your Mergify configuration file. Be sure to verify the syntax and structure of your configuration file.
If a pull request ends up in an unexpected position in the queue:
Verify the priority assigned in the priority rule. A higher value or a higher priority keyword (e.g., "high") will place the pull request closer to the front of the queue.
Make sure there isn't another priority rule that is placing the pull request at a different position.
Confirm that your priority rules are correctly set up in the queue rule. The priority rules should be nested under the correct queue rule in your configuration file.