Using Priorities

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.

Understanding Priority Rules

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 low, medium, 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.

Here is a glimpse into the structure of a priority rule:

1
queue_rules:
2
  - name: default
3
    queue_conditions:
4
      - "#approved-reviews-by>=2"
5
      - check-success=Travis CI - Pull Request
6
    priority_rules:
7
      - name: high priority
8
        conditions:
9
          - label=urgent
10
        priority: high
11
      - name: low priority
12
        conditions:
13
          - label=refactor
14
        priority: low

In the above configuration:

• The priority_rules section sets up priority rules for the queue named default.

• Two priority rules, high priority and low priority, are defined.

• Each rule contains conditions (label=urgent and label=refactor, respectively) which, if met, apply a certain priority to the pull request (high or low). Pull requests that match no priority rules get assigned to medium priority.

• 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.

How to Define Priority Rules

Defining priority rules is straightforward and involves the following steps:

1. Choose a queue: Priority rules are tied to a specific queue. So, first, choose the queue where you want to apply these rules.

2. Define priority levels: Decide on the levels of priority you want to establish for your pull requests. You can use either keywords (low, medium, high) or numerical values for this purpose.

3. 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.

Reference:

The textual priorities have the following numerical values:

Let's look at an example:

1
queue_rules:
2
  - name: default
3
    queue_conditions:
4
      - "#approved-reviews-by>=2"
5
      - check-success=TeamCity
6
    priority_rules:
7
      - name: urgent fixes
8
        conditions:
9
          - label=urgent
10
          - label=bug
11
        priority: high
12
      - name: low-priority tasks
13
        conditions:
14
          - label=refactor
15
        priority: 10

In this configuration:

• We are defining priority rules for the default queue.

• Two priority levels are set up: high for urgent bug fixes and 10 for refactoring tasks.

• The conditions for the high priority level are that the pull request has labels urgent and bug.

• The condition for the low-priority tasks is that the pull request has the refactor label.

Managing Check Interruptions Based on Priority

The 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.

Conversely, if 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.

1
queue_rules:
2
  - name: default
3
    merge_conditions:
4
      - "#approved-reviews-by>=2"
5
      - check-success=TeamCity
6
    allow_checks_interruption: false
7
    priority_rules:
8
      - name: urgent
9
        conditions:
10
          - label=urgent
11
        priority: high
12
      - name: normal
13
        conditions:
14
          - label=normal
15
        priority: low

In this configuration, allow_checks_interruption is set to false. This 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 with the normal label. Instead, it will wait for the normal pull request's checks to complete before starting its own checks.

Advanced Priority Rule Usage

Beyond the basic use of priority rules, you can leverage advanced features to fine-tune how your pull requests are prioritized in the queue.

Using Numerical Values

While the keywords (low, medium, 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.

For example:

1
priority_rules:
2
  - name: extremely urgent
3
    conditions:
4
      - label=critical
5
    priority: 5000

In this rule, pull requests labeled critical are given a very high priority.

Mixing Keywords and Numerical Values

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).

1
priority_rules:
2
  - name: important task
3
    conditions:
4
      - label=important
5
    priority: high
6
  - name: critical task
7
    conditions:
8
      - label=critical
9
    priority: 5000

In this configuration, critical tasks are treated with the utmost urgency, while important tasks also receive high priority but are placed after critical tasks in the queue.

Complex Condition Definitions

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 /src directory:

1
priority_rules:
2
  - name: core changes
3
    conditions:
4
      - files~=^src/
5
    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.

Troubleshooting Priority Rules

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:

Priority Rule Not Applied

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.

Unexpected Queue Position

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.